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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this mutates the document without destroying content. The description adds nothing beyond 'by their UUIDs' – it does not explain what state changes occur, whether prior selection matters, or how the operation interacts with the active artboard.

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 front-loaded sentence with no wasted words. It is appropriately sized for the tool, though 'and/or' is a small ambiguity that a slightly more explicit phrasing could resolve.

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?

No output schema exists, and annotations cover the safety profile, so the burden shifts to the description to convey behavior. For a mutation tool this is minimally adequate: the rich schema covers parameters, but nothing states required document state or how results manifest.

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

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

Schema description coverage is 100%, so all five parameters (including enums and the coordinate_system nuance) are already documented in the schema. The description only restates the UUID input concept, adding no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (align/distribute) and resource (multiple objects), identified via UUIDs. This distinguishes it from siblings like select_objects or modify_object, though it does not explicitly name an alternative. The two behaviors (align and distribute) are named but not separated.

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 versus alternatives such as modify_object or select_objects, and no prerequisites (e.g., needing an active document or pre-existing selection). The 'and/or' leaves the agent to infer whether alignment and distribution are mutually exclusive or combinable.

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 mutation profile (readOnly=false, destructive=false, non-idempotent). The description adds genuinely useful execution context — background mode with no Illustrator activation and no Computer Use invocation — but says nothing about what happens to existing appearances or whether target UUIDs must be selected/visible.

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 zero waste; the core purpose is front-loaded and the execution-mode note follows as supporting context.

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

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

For a three-parameter mutation tool with no output schema, the definition covers the purpose but omits how the style is identified, what the response looks like, and any failure conditions (e.g., unknown style name or invalid UUIDs).

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

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

Schema description coverage is 100%, so merge/uuids/style_name are fully documented in the schema itself. The description adds no parameter-level meaning beyond that, which makes the baseline 3 appropriate.

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

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

States a specific verb and resource ('Apply a graphic style to objects'), which distinguishes it from sibling apply_text_style by the resource. It does not, however, explicitly name the sibling it differs from or clarify how it relates to list_graphic_styles.

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 versus alternatives such as apply_text_style or run_script, and no stated precondition (e.g., that the style name must already exist, discoverable via list_graphic_styles). The agent must infer the workflow entirely.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely non-redundant behavioral context: it runs without activating Illustrator in default background mode and never uses Computer Use, which tells an agent this is safe to run headlessly. It does not, however, disclose what clear_overrides destroys or how failures surface.

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 purpose front-loaded and no filler. The second sentence is somewhat tangential to purpose but still carries useful execution-mode information, so it 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?

Parameters and annotations are fully specified, but with no output schema the description never indicates what a successful call returns, whether the operation is reversible (an 'undo' sibling exists), or how to recover from a failed application. Adequate but with clear gaps for a mutating tool.

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

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

Schema description coverage is 100% with all four parameters documented, including the style_type enum, so the schema carries the full parameter burden. The description adds no format or constraint detail beyond it, matching the baseline 3.

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 ('Apply a character or paragraph style to a text frame') and the style_type enum narrows it precisely. This distinguishes it from siblings like apply_graphic_style and list_text_styles without the agent needing to open a schema.

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

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

Usage is implied by the verb (apply an existing style to a text frame) but there is no explicit when-to-use guidance, no mention of how to discover valid style names (e.g. list_text_styles), and no statement of when to prefer apply_graphic_style instead.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them by clarifying the effect is tag-only with no ICC conversion, plus a note on background execution. It still doesn't explain why the op is destructive or whether the change is reversible.

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

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

The action is front-loaded, followed by a clearly-marked warning and the alternative, so an agent reading only the first sentence grasps the tool. The closing note about not invoking Computer Use is slightly meta but does not bury the key content.

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

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

For a single-parameter mutation with no output schema, the description supplies purpose, the key caveat, and the alternative. It is largely complete; the only minor gap is the absence of any note on reversibility or required context, which the destructiveHint hints at but does not explain.

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

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

Schema coverage is 100% and the single 'profile' parameter is documented as 'Color profile name or path'. The description adds no syntax, format, or naming detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Assign (tag) a color profile to the document') and immediately disambiguates it from the similarly-named conversion operation. An agent can tell it apart from siblings like replace_color or manage_swatches without opening any schema.

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

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

Clearly states the boundary of the tool ('only changes the profile tag — it does NOT convert color values') and points to the alternative for full conversion. However, the alternative named is an Illustrator UI path rather than a sibling MCP tool, so routing among the listed tools is not fully resolved.

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

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

With destructiveHint=true, openWorldHint=false already declared, the description adds substantial context: it is a detached/async job whose return is acceptance not completion, it makes no image downscaling and has no UI fallback, it removes template copies, and it reopens documents for structural checks. This goes well beyond what the annotations convey and is highly actionable.

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

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

Purpose is front-loaded in the first sentence and every sentence carries operational information. It is dense and slightly run-on in the middle process narration, but nothing is filler and nothing important is buried.

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

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

For a complex, mutation-heavy, async tool with no output schema and sparse parameter documentation, the description covers the critical unknowns: async behavior, next-step polling, template verification prerequisite, and preview inspection. It falls short only on the un-narrated layout parameters.

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

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

Schema description coverage is only 29%, so the description must carry more weight. It conceptually explains cards (text/image replacement), name_art PDF path import and backing construction, but says nothing about columns, gap_pt, template_artboard, expected_sublayers, or aligned_image_pairs, leaving several parameters undocumented in both places.

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

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

The opening sentence gives a specific verb and resource ('Start a detached background card job from a saved normalized AI template and confirmed content'), which is far more precise than the bare name 'batch_cards'. It implicitly separates itself from validate_cards (template must be verified first) and get_batch_status (poll after), though it never states the card-generation vs. validation boundary outright.

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

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

It states a clear precondition ('verify the template first', 'One simple card template per source document') and a clear follow-up ('poll get_batch_status and visually inspect previews'). It names sibling tools for the surrounding workflow, but does not discuss when this tool is the wrong choice or what alternatives exist for other card scenarios.

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 destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely non-obvious behaviour: face holes are preserved, face and backing remain separate objects, and 'visual review is still required' warns the agent that output may not look correct. It still omits whether the source face is modified or what the tool returns.

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-loaded with the operation and followed by the two actionable caveats. No filler; the only mild dilution is the middle sentence, which could be merged into the parameter clause.

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

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

No output schema and no annotation-level detail on mutation semantics, so the description must be self-sufficient. It covers behaviour well but leaves a 4-required-parameter, nested-object schema largely opaque, which is thin for a destructive compound operation.

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 carries the full load. It meaningfully explains the gradient_name-vs-stops fork and that bounds/thickness (offset_pt) are in native document points, but document_path, root_layer_path, face_name, backing_name and angle get no explanation at all.

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

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

States a specific compound verb+resource: duplicate a name face, apply a gradient, attach an Offset Path effect. An agent can tell it apart from generic siblings like duplicate_objects or duplicate_layer_tree. It stops short of explicitly naming which sibling to prefer when the goal is simpler.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative (create_gradient, duplicate_objects, apply_graphic_style are all plausible neighbours). The only routing hint is the implicit 'template gradient or explicit RGB stops' fork, which is about parameters, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds an edge-case note about GrayColor's ink-quantity interpretation differing from the API reference, which is valuable domain-specific behavioral context, but does not cover return values or failure modes. With annotations already covering safety, a 3 is appropriate.

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

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

Three sentences, front-loaded with the core purpose, then modes, then an important caveat. Zero waste; every sentence earns its place.

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

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

Given readOnly annotations, 100% schema coverage, and no output schema, the description covers the purpose, modes, and a non-obvious edge case (GrayColor). It's complete enough for an agent to call correctly, though it could mention output format or how WCAG thresholds are reported.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including nested color objects with types (cmyk/rgb/gray). The description implies the manual mode requires two color objects, but does not add meaning beyond the schema for individual color properties. Baseline 3 is correct when schema does the heavy lifting.

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

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

States a specific verb and resource: check WCAG color contrast ratios. It distinguishes two operating modes (manual vs auto), which is useful. However, it doesn't differentiate itself from siblings like get_colors or preflight_check, which might relate to color/compliance checks, so sibling differentiation is absent.

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

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

Explicitly describes two usage modes: manual mode requires providing two colors, auto mode detects overlapping pairs. This tells the agent when to use each mode, though it doesn't state when to use this tool versus alternatives like get_colors or preflight_check.

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 establish read-only, idempotent, non-destructive behavior, so the bar is lower, and the description still adds real value: it discloses that it returns all text contents, that deeper analysis is LLM-driven, and that the AI analysis may miss errors and does not replace human review. That caveat is exactly the kind of trust-calibration context annotations cannot express. It omits scope/pagination details, so not a 5.

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

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

Three tight sentences with the core capability front-loaded and the limitation note placed last where it belongs. The phrase 'for LLM-driven deeper analysis' is slightly meta but still earns its place by setting expectations about output.

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 description correctly carries the burden of describing the return ('Returns all text contents') and the reliability caveat. What is missing is scope clarity — whether the scan covers the whole document or only the filtered artboard — which matters given the artboard_index filter.

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

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

Schema description coverage is 100%, so both artboard_index and coordinate_system are fully documented in the schema, including the auto-detection rule and the pointer to get_document_info. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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

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

The description names a specific verb and resource ('Analyze text frames') plus the concrete detection targets (dummy/placeholder text, katakana long vowel, fullwidth/halfwidth, wave dash/tilde), which is far more informative than the title. It stops short of explicitly distinguishing itself from close siblings like list_text_frames or get_text_frame_detail, which an agent might also consider for text 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?

Usage is only implied: the reader infers this is a pre-handoff QA/consistency check on document text. There is no explicit when-to-use, no statement of when to prefer this over list_text_frames or get_text_frame_detail, and no mention of prerequisites or scope (whole document vs. active artboard).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a risky mutation. The description adds useful execution context (background mode, never invokes Computer Use), but omits the critical consequence that unsaved changes are lost given save defaults to false.

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, purpose front-loaded, no filler. The execution-mode note is compact and earns its place for an agent operating in headless contexts.

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 annotations covering the destructive profile and the schema covering the save flag, the description only needs to add operational context, which it does via the background-mode note. Minor gap: it never states what happens to unsaved work when save is omitted.

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

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

Schema coverage is 100% and the single 'save' parameter is fully documented there, including its default. The description adds no syntax or behavior detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Close the active Illustrator document'), which is unambiguous and clearly separable from siblings like save_document, create_document, or open_document. No ambiguity about scope ('active' 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?

No guidance on when to use this versus save_document or delete_objects, and no mention that closing discards unsaved state unless save=true. The one implicit context is that it assumes an active document exists, which is never 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the 'active document' scoping context; it says nothing about out-of-bounds points, whether units matter, or precision/rounding behavior.

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

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

One sentence, no filler, scoping detail front-loaded. Nothing could be removed without losing 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, annotation-covered pure function the description is nearly adequate, but with no output schema it never states what is returned (a converted {x, y} point, and in which units/frame). Nested point object handling is also left entirely to the schema.

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

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

Schema description coverage is 100% and both enum parameters are self-documented ('Source coordinate system', 'Destination coordinate system'), so the baseline of 3 applies. The description's only parameter-relevant signal is that 'from'/'to' must be the two named systems, which the enum already conveys.

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?

Specific verb (convert) plus a precise resource (a point between artboard and document coordinate systems) and scope (the active document). No sibling tool performs coordinate translation, and the description makes the transformation direction explicit via 'between ... and ...'.

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

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

Usage is implied rather than stated: an agent can infer this is for translating coordinates when crossing the artboard/document boundary, and 'in the active document' hints at a precondition. However, there is no explicit when-to-use trigger, no statement that this is the only supported conversion path, and no note about needing an open document with artboards.

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 execution-mode context ("runs without activating Illustrator in default background mode; never invokes Computer Use") that annotations do not cover. But for a tool annotated destructiveHint=true and idempotentHint=false, it never says what is destroyed: the text loses editability and the conversion is not reversible. That is the most important behavioral fact and it is left to inference.

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, core action front-loaded, and the runtime caveat second. 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?

There is no output schema, so the description carries the return-value burden and stays silent on it. For a destructive, non-idempotent operation on a single required target, it should at least note irreversibility or the undo path (a sibling `undo` exists).

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

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

Schema description coverage is 100% and the single target parameter is fully documented in the schema, including the "selection"/"all"/layer-name semantics. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource ("Convert text to outlines"), which is unambiguous and matches the title. However, it does not distinguish itself from the many other text-related siblings (list_text_frames, apply_text_style, create_path_text) or explain what "outlines" means operationally (text becomes vector paths).

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

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

No when-to-use guidance, no prerequisites, and no mention of when this is preferable to run_script or other text manipulation tools. The two sentences address execution mechanics, not selection criteria.

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 only cover the safety profile (readOnlyHint=false, destructiveHint=false); the description goes further by disclosing that the default path expands the artboard to include all marks (a side effect the annotations do not reveal) and that use_selection leaves the artboard untouched. It also adds runtime context ('runs without activating Illustrator in default background mode; never invokes Computer Use'), which materially affects how an agent should call 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?

Four tightly packed sentences, front-loaded with the artifact and its scope before the mode-dependent behavior. Every sentence carries distinct information (default vs selection behavior, style auto-detection, background execution).

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

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

For a 4-param creation tool with no output schema, the description covers scope, side effects, and execution mode adequately. It does not describe what the tool returns or any confirmation of created marks, which is a minor gap given there is no output schema to rely on.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description largely restates what the schema already says about use_selection and style, adding only the artboard-expansion consequence. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Create crop marks (トンボ / trim marks)') and names the two scopes it operates on (active artboard or selected objects). No sibling tool does crop marks, so it is unambiguously distinguishable from the surrounding create_*/get_* set.

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

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

Clearly contrasts default behavior ('creates marks for the artboard') against use_selection=true ('creates marks for the currently selected object(s) without modifying the artboard'), giving the agent a decision rule. It stops short of naming an alternative sibling or an explicit when-not-to-use, so it is not a 5.

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

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

Annotations already specify openWorldHint=false and destructiveHint=false, covering safety. The description adds operational detail: it runs in default background mode and never invokes Computer Use, which is useful context about execution environment. However, it doesn't disclose whether the new document becomes active or how defaults are applied.

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

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

The description is two concise sentences with no wasted words, front-loading the core purpose.

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

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

Given the simplicity of a 3-parameter creation tool with full schema coverage and annotations, the description is adequate but could mention what happens on success (e.g., returns document reference) or interaction with existing documents. No output schema exists, so return behavior is unknown.

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

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

Schema coverage is 100%, so parameters width, height, and color_mode are fully documented in the schema. The description adds no additional parameter information, so the baseline of 3 is appropriate.

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

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

The description states a clear verb+resource: 'Create a new Illustrator document.' This distinguishes it from sibling creation tools like create_rectangle or create_text_frame. It does not explicitly differentiate from open_document, but the resource 'document' is specific.

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

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

There is no guidance on when to use this tool versus siblings like open_document or set_workflow. The description only states what it does, not the context for use.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds operational context about execution mode (background mode, no Computer Use), which is genuine added value, but says nothing about which document/artboard receives the object, layer defaults, or whether it fails without an open document.

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 action ('Create an ellipse') before the execution-mode note. Nothing is padded, though the second sentence reads as server-wide boilerplate that could be trimmed or replaced with tool-specific 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?

For a 9-parameter creation tool with nested color objects and no output schema, the description is minimally viable: the rich schema lets the agent construct the call, but the description omits how the created ellipse is identified/returned for follow-up operations and whether a target document must already be open.

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

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

Schema description coverage is 100%, including a well-documented coordinate_system enum with auto-detection rules, so the schema does the heavy lifting and the baseline is 3. The description adds no parameter-level meaning (no note on fill/stroke defaults, layer_name behavior, or units) beyond what the schema already says.

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

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

States a specific verb+resource ('Create an ellipse'), matching the name precisely and clearly placing it among the sibling create_* tools (create_rectangle, create_line, create_path). It does not, however, explicitly differentiate itself from those siblings or state what shape/scope is produced.

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

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

There is no guidance on when to use this versus create_rectangle, create_path, or create_line, nor any prerequisites (e.g., an open document, active artboard) or conditions under which it should not be used. The agent is left to infer usage entirely.

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 cover the safety profile (readOnlyHint=false marking a write, destructiveHint=false), lowering the bar, and the description adds genuinely useful runtime context: it runs in background mode without activating Illustrator. It still omits mutation-specific behavior such as duplicate-name handling (relevant given idempotentHint=false) and whether applying overwrites existing fills.

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

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

Two tight sentences with the core action front-loaded. The execution-mode clause is a little tangential but compact and non-redundant.

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 covers purpose and execution but says nothing about the return value or where the created gradient lands (swatch library vs document), leaving the agent to infer the outcome.

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

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

Schema description coverage is 80%, so the schema does the heavy lifting on name, type, angle, stops and apply_to_uuids. The description adds no parameter-level meaning (e.g., stop ordering or how apply_to_uuids interacts with the created gradient), so the baseline 3 is appropriate.

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

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

States a specific verb ('Create') and resource ('a gradient in the document') plus its optional secondary effect ('apply it to objects'). No sibling tool creates gradients, so it is trivially distinguishable from the rectangle/ellipse/path creation 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 gives no when-to-use or when-not-to-use guidance, and names no alternative (e.g., manage_swatches for existing gradients). An agent gets the operation but no routing context.

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, and non-idempotent, so the safety profile is partly covered. The description adds genuinely new behavioral context about running in default background mode without activating Illustrator or invoking Computer Use, but omits whether it modifies the active document or what it appends to.

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 packed sentences with the core action front-loaded and zero filler. Nothing is redundant and the execution-mode note is kept brief.

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 rich schema fully covers all 8 parameters and there is no output schema to explain, so return values need no mention. Still, for a document-mutating creation tool the description leaves out prerequisites and interaction with the target document/layer, leaving modest 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 100%, with x1/y1/x2/y2, the nested stroke object, and the coordinate_system enum all documented inline. The description adds no meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Create a line"), which cleanly distinguishes it from the shape siblings create_rectangle and create_ellipse. However it never contrasts itself against create_path, which also draws geometry, so the boundary is not spelled out.

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

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

There is no guidance on when to use create_line versus alternatives such as create_path or the other create_* shape tools, and no stated prerequisites (e.g. whether a document must be open). The second sentence describes execution mode, not usage context.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, telling the agent this is a non-destructive write. The description adds a genuine non-annotation detail (background mode, no Computer Use), but omits mutation specifics such as which document/layer is affected and whether the action is undoable.

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 no filler. The second sentence is somewhat tangential (execution environment) but short and plausibly useful to an agent deciding how to invoke it.

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

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

With 7 parameters, nested anchor objects, and no output schema, an agent has enough from the schema to construct the call. However the description does not say what is returned, whether the path is created on the active document or layer, or how it interacts with layer_name, leaving moderate gaps for a creation tool.

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

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

Schema description coverage is 100%, with anchors, fill, stroke, coordinate_system and layer_name all documented in the schema, including the enum's auto-detection logic. The description contributes nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a custom path'), which clearly reads as freeform anchor-based drawing. It does not distinguish itself from the sibling creation tools (create_rectangle, create_ellipse, create_line, create_path_text), so an agent must infer that 'custom path' means arbitrary anchors rather than a primitive.

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

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

There is no when-to-use guidance and no mention of alternatives such as create_line, create_rectangle, or import_svg_as_editable for arbitrary geometry. The only extra sentence is about execution mode, not about tool selection or prerequisites.

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 declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, so the mutation profile is covered. The description adds genuine execution context ('background mode', 'never invokes Computer Use'), but says nothing about whether an existing path text is replaced or how failures on a bad path_uuid behave.

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, purpose first, no padding or repetition of the title. The second sentence is meta rather than domain behavior, but it is brief and does carry 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 creation tool with no output schema, the definition is adequate but thin: it never says what the call yields (e.g., a new text-frame handle/name) or what happens on an invalid path_uuid. The background-mode note helps, but the create-side contract is left to the schema.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the useful cross-reference to list_fonts in font_name. The description adds no parameter-level meaning beyond the schema, which is the expected baseline at full 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 gives a specific verb and resource ('Create a text frame that flows along a path'), which implicitly separates it from the sibling create_text_frame. It stops short of naming that sibling explicitly, so the differentiation is inferable rather than stated.

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 instead of create_text_frame or create_path, and no prerequisites stated (e.g., that path_uuid must reference an existing path item, obtainable via get_path_items). The agent must infer usage entirely.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description does add genuinely new context by disclosing the non-activating background execution path and that Computer Use is never invoked, but it says nothing about the resulting object's state (selection, layer placement) or failure 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?

Two short, front-loaded sentences with no filler; the purpose leads and the execution-mode caveat follows. The second sentence is somewhat narrow in focus but does earn its place as non-obvious 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?

For a 10-parameter mutation tool with nested fill/stroke objects and no output schema, the description is thin: it omits defaults (corner_radius=0), layer targeting behavior, and what is returned or selected after creation. The very rich schema and existing annotations compensate substantially, keeping this at a minimum-viable 3.

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

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

Schema description coverage is 100%, including a rich explanation of coordinate_system and the nested fill/stroke color variants, so the schema carries the parameter burden. The description adds no parameter-level meaning beyond that baseline, so a 3 is appropriate.

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

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

The description states a specific verb+resource ('Create a rectangle'), which is unambiguous. However, it offers no differentiation from the numerous sibling creation tools (create_ellipse, create_line, create_path, create_text_frame), so the agent must rely on the name alone to choose among them.

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

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

There is no when-to-use guidance, no preconditions (e.g., a document must be open, a target layer must exist), and no mention of alternatives. The only contextual sentence concerns execution mode, not selection between tools.

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

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

Annotations already declare the write/non-idempotent/non-destructive profile, so the bar is lower. The description adds genuinely new context beyond annotations: it runs in background mode without activating Illustrator and never invokes Computer Use, which tells the agent this call will not hijack the user's UI session. It stops short of describing return behavior or how the new frame is identified.

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 purpose front-loaded and no filler. The second clause is slightly redundant ('without activating Illustrator' vs 'never invokes Computer Use'), which keeps it from a 5.

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

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

For a 12-parameter creation tool with no output schema, the definition covers purpose and execution mode but omits selection guidance against sibling creators and says nothing about what is returned (e.g., the new frame's id/name). The annotation set is minimal, so the description leaves gaps an agent must infer.

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

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

Schema description coverage is 100% and the schema is unusually rich (coordinate_system, contents, font_name, fill variants all documented). The description adds no parameter meaning whatsoever and no cross-parameter relationships (e.g., width/height only applying to 'area' kind), so baseline 3 is correct.

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

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

The description says 'Create a text frame,' which names a concrete verb and resource rather than a vague process, so it is more than empty noise. However it essentially restates the tool name/title, and it does not differentiate from adjacent creation tools such as create_path_text, create_rectangle, or create_path. No scope or output is characterized.

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 statement of when to use this tool versus alternatives (create_path_text, create_rectangle, etc.), no prerequisites, and no conditions. The only sentence beyond the purpose describes execution mode, which is behavioral rather than usage 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?

Beyond the destructiveHint=true annotation it discloses concrete behavior: locked objects are skipped unless force_unlock is set, the operation is reversible via the undo tool, and it runs without activating Illustrator (no Computer Use). Those are exactly the operational details annotations cannot express.

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, front-loaded with the core action and identifier, then constraints, then alternatives, then execution mode. No filler and nothing repeated from the schema.

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 two-parameter mutation with no output schema, everything needed to call it safely is present: identifier sourcing, lock handling, reversibility, execution environment, and the layer-wide alternative.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description still adds meaning by explaining the interaction between them: force_unlock exists specifically to override the locked-object skip. Slightly above the baseline 3 because it clarifies conditional behavior rather than restating field names.

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

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

States a specific verb and resource with the identifier type ('Delete one or more objects by UUID'), and distinguishes itself from layer-level deletion by naming manage_layers. An agent can pick this out from siblings like duplicate_objects or select_objects immediately.

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

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

Explicitly routes the agent for UUID discovery (find_objects / get_layers / get_selection), states the locked-object condition, names an alternative for a different scope (manage_layers), and points to the undo path. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds real value beyond that: preservation of item order, clipping groups and child layer state, plus a disclosed refusal condition for duplicate targets. Auth requirements and document-side effects remain undocumented, keeping it short of a 5.

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

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

Three sentences, front-loaded with the core action and with no filler. The trailing coordinate/refusal notes are compact, though the coordinate remark is only loosely tied to the actual parameters.

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

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

For a mutating tool with no output schema and five parameters at 0% schema coverage, the description gives good preservation semantics but insufficient parameter documentation. An agent knows the intent yet lacks format guidance for the path and offset inputs.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely fails it. It vaguely gestures at the target parent and "native document coordinates in points," but leaves offset_x/offset_y, the document_path format, and the nested-array structure of source_layer_paths entirely unexplained.

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

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

The description uses a specific verb ("Copy") and resource ("a complete layer hierarchy") and states where it lands ("into a new parent layer in the specified open document"). It implicitly separates itself from sibling duplicate_objects by scoping to layer hierarchy rather than objects, though it never names that sibling.

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

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

Usage is implied rather than stated: "in the specified open document" signals the document must be open, and "Refuses a duplicate target parent" hints at a precondition. No explicit when-to-use or when-to-prefer-duplicate_objects guidance is provided, so the agent must infer the 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 declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the description only needs to add context. It does add genuinely useful execution context: the operation runs in background mode without activating Illustrator and never uses Computer Use. It omits other relevant behavior such as whether the originals remain selected, whether duplicates inherit the source layer, or what is returned.

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, purpose front-loaded, zero filler or restatement of the title. Every clause contributes either the core action or distinct execution context.

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

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

For a mutation tool with no output schema and full schema coverage, the description is minimally adequate: it says what happens and how it executes. It leaves out sibling differentiation (duplicate_layer_tree), post-condition state (selection/layer of the new copies), and error expectations when a UUID is invalid or the target layer does not exist.

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

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

Schema description coverage is 100% with four well-documented parameters, including the coordinate_system enum with a full explanatory note and a pointer to get_document_info. The description repeats only the 'optionally offsetting' idea already implied by the offset parameter, adding no new semantic detail, but the baseline for full schema coverage is 3 and the nested-object/enum documentation here is unusually thorough.

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 ('Duplicate one or more objects') plus an optional behavioral nuance (offsetting the copies). It does not, however, distinguish itself from the closely related sibling 'duplicate_layer_tree', so an agent cannot immediately tell which duplicator applies to its case.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of the obvious alternative 'duplicate_layer_tree' or of 'move_to_layer' for repositioning. The agent must infer scope from the tool name alone.

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

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

Beyond the annotations (which only declare the safety profile), the description discloses execution mode ('runs without activating Illustrator in default background mode; never invokes Computer Use') and the crucial return-shape difference: single PNG/JPG come back as base64 in the response while artboard:all returns file paths only. That is exactly the behavioral context an agent needs and cannot get from the structured fields.

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

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

Four sentences, all front-loaded and substantive: purpose, batch target, return format, execution mode. Every sentence earns its place, with only minor overlap with the schema's own artboard:all note.

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 nested option objects and no output schema, the description supplies the missing return-value semantics (base64 vs. file paths) and execution context. It leaves output_path behavior and the temp-document side effect to the schema, which is acceptable, but a note on permissions or error cases would round it out.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning for the target/format interaction (base64 image returned for single PNG/JPG, paths only for artboard:all) that helps the agent pick parameter values. The artboard:all filename-suffix detail is redundant with the schema, keeping this below a 5.

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 (Export) and enumerates the resources it operates on: objects, groups, artboards, selection. It's immediately clear what the tool does. It does not, however, differentiate itself from the sibling export_pdf, leaving the agent to infer which export path to take.

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

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

It gives a conditional for one target value ('Use target "artboard:all" to batch-export every artboard in one call') and explains when base64 vs. file-path returns occur. But it never states when to prefer this tool over export_pdf or other siblings, and gives no prerequisites or exclusions. Usage is implied rather than prescribed.

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 idempotent=true, destructive=false, and readOnly=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: it runs without activating Illustrator, never invokes Computer Use, and its output needs human verification. It does not cover file overwrite behavior or failure modes, keeping it short of a 5.

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

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

Three short sentences with the core action front-loaded and no filler. The final human-verification warning is slightly advisory but earns its place as a workflow constraint for a print-ready deliverable.

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 three parameters, a nested options object, and no output schema, the description is minimally adequate: it says what the tool produces but not what is returned (e.g. the resulting file path) or what happens when output_path already exists. It is sufficient to invoke correctly but leaves the agent guessing about results and side effects.

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

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

Schema description coverage is 100%, including the nested options object with per-field descriptions, so the schema carries the full parameter burden. The description adds no meaning about preset, options, or output_path beyond what the schema states, making the baseline 3 correct.

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

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

The description opens with a specific verb+resource ("Export print-ready PDF") and clarifies the output is print-ready, which is meaningful. However, it never differentiates itself from the sibling tool "export" or from preflight_check/validate_cards, leaving the agent to guess when this PDF-specific export is preferred.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as the generic "export" sibling. The only routing-adjacent statement is about execution mode (background, no Computer Use), which describes how it runs rather than when to pick 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that output can be a file artifact, which is useful, but it doesn't disclose return structure, whether extraction is lossy, or how output_path interacts with permissions. Adds some value on top of annotations but not rich 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?

A single front-loaded sentence that names the extraction targets before the output choices, with no filler or redundant clauses. Every phrase 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 read-only, single-purpose extraction tool with no output schema, the description covers the core inputs and output shape adequately. A bit more on what the emitted token set contains (or how output_path omission behaves) would close the remaining gap, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the enum values and output_path semantics are already fully documented. The description restates the three formats, which duplicates the enum rather than adding syntax or behavior detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Extract) and resource (design tokens) and enumerates exactly what it pulls: colors, typography, and spacing. An agent can distinguish it from get_colors or list_text_styles, which return raw primitives rather than consolidated tokens. No sibling is named, so differentiation is implicit rather than explicit.

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?

Listing the three output formats (CSS custom properties, JSON, Tailwind) implies the use case of porting design values into a code-consumable artifact. However, it never says when to prefer this over get_colors/export, or any exclusions, so guidance remains 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds nothing beyond that — no note on result size, scoping to active document, or behavior when no criteria are supplied, which is real context for a search 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?

A single front-loaded sentence with no wasted words. It is efficient, though the terseness is a symptom of under-specification rather than admirable restraint.

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 9 parameters, nested color objects, two enums, and no output schema, the definition should say something about the returned shape (objects, ids, or full details) and how criteria combine. Neither is addressed, so the definition is incomplete for the tool's complexity.

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

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

Schema description coverage is 100%, including detailed tolerance and coordinate-system semantics, so the schema carries the full burden. The description adds no parameter meaning beyond the schema, which lands at the baseline of 3.

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 (search/find) and resource (objects) with the scoping notion of criteria-based lookup. It is clear on its own, but it offers no differentiation from siblings that also retrieve object collections such as get_groups, get_layers, or select_objects.

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

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

There is no guidance on when to use this versus the many other listing/retrieval siblings, no statement of prerequisites, and no mention of whether criteria are AND-combined or what happens with zero criteria. The agent must infer everything from the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on return volume, ordering, or pagination for a list-all call.

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

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

A single five-word sentence with no waste, but it errs toward under-specification rather than useful brevity — there is essentially no content to front-load.

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 description should explain what 'artboard information' means, since that phrasing implies a return shape the agent cannot otherwise predict. It also fails to resolve the all-vs-index tension, leaving the tool under-described for its scope.

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

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

Schema coverage is 100%, including a detailed coordinate_system description, so the schema carries all parameter meaning. The description contributes zero additional parameter context, which matches the baseline 3 for fully-covered schemas.

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

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

States a verb and resource (get artboards information), which is minimally clear, but 'all' is misleading given an index parameter exists for fetching a single artboard, and nothing distinguishes it from the sibling manage_artboards.

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 versus manage_artboards or get_document_structure. The schema hints that get_document_info is relevant for the coordinate system, but the description itself never routes the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by listing the returned artifacts and, crucially, decoding a status value ('ready_for_visual_review means structural checks passed, not visual approval') and forbidding auto-restart of failed jobs. That is real context beyond structured fields, though it says nothing about polling cadence or job retention.

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

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

Three compact sentences, front-loaded with the read action and return contents, then the status-semantics caveat and the restart warning. Every sentence carries content, though the first sentence is a dense packed list rather than a clean statement of intent.

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

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

With no output schema, the description carries the return-value burden and does it reasonably: progress, plan, log and preview paths plus the meaning of the key status flag. What remains thin is the input side (how to obtain a valid job_id) and any note on long-running or partial jobs.

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?

One parameter with 0% schema description coverage, so the burden falls on the description, which only indirectly covers job_id via 'Read a background card job' — it never says the id is the UUID returned by batch_cards or what happens on an unknown/expired id. Marginal compensation for the coverage gap.

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

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

States a specific verb (Read) and resource (a background card job) and enumerates what it surfaces: per-card progress, prepared plan, log and preview paths. Against siblings like batch_cards, validate_cards and get_runtime_status, an agent can tell what this returns without opening any schema.

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

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

Usage is implied — poll this after starting a card job — but no alternative is named and no when-not condition is given, aside from a behavioral prohibition ('Never automatically restart failed or unconfirmed jobs'). That prohibition is guidance about how to act on the result, not about choosing this tool over a sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without description help. The description adds only the 'used in the document' scoping qualifier; it does not mention that output composition varies by the three include flags or note that swatches may be returned even when unused.

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 front-loaded sentence with no filler. The core verb and scope appear immediately, which is ideal for a low-complexity read tool.

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 three-optional-flag read tool with full schema coverage and no output schema, the definition is minimally adequate but leaves the agent guessing about what the return payload contains and how the include flags shape it. Given the absence of an output schema, a sentence about the return shape would have been warranted.

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

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

Schema description coverage is 100%, so all three boolean flags (include_swatches, include_diagnostics, include_used_colors) are already documented with defaults in the schema. The description mentions 'color information' generically but does not explain the print-diagnostics or swatch toggles, so it adds nothing beyond 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 names a specific verb (Get) and resource (color information) with a clear scope qualifier ('used in the document'), so an agent knows it returns document color data rather than swatch management. It does not distinguish itself from adjacent siblings like manage_swatches, list_graphic_styles, check_contrast, or replace_color.

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

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

There is no guidance on when to choose this tool over manage_swatches, list_graphic_styles, or check_contrast, nor any exclusion such as 'swatches only, not used colors'. The agent must infer usage purely from the name and sibling list.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no indication of what metadata is returned, whether it is cached, or what fields it exposes.

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 words is not conciseness but under-specification; the sentence does not earn its place because it carries no information beyond the tool name and title. Compare the calibration low example where 'Process' scored 2 for the same reason.

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 description is the only place an agent could learn what this call returns, yet it explains nothing about the returned metadata shape or contents. For a zero-argument utility that other tools reference, this leaves a notable gap.

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

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

Schema description coverage is 100%, and the single optional coordinate_system parameter is thoroughly documented in the schema itself (enum values, auto-detection behavior, origin semantics). The description contributes nothing to parameter meaning, but per the high-coverage baseline a 3 is appropriate.

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

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

The description 'Get document metadata' essentially restates the tool name and title ('Get Document Info') without adding specificity. It does not distinguish this tool from close siblings like get_document_structure, get_runtime_status, or get_artboards, so an agent cannot tell what kind of metadata is returned.

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

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

There is no when-to-use guidance, no alternatives named, and no conditions described. Interestingly, the input schema for the sibling parameter mentions calling get_document_info to check the active coordinate system, but that routing hint appears in another tool's schema rather than in this description.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds no behavioral context beyond the purpose line — nothing about output size on large documents, truncation, or cost of traversing deep trees.

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, front-loaded sentence with no filler. It is efficient, though arguably terse for a tool that returns a nested document tree and could use one clause about scope.

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

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

For a read-only enumeration tool the description is minimally adequate. No output schema exists, so the description could have clarified the returned tree shape, but the absence of behavioral gaps is smaller given the annotations and full parameter coverage.

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

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

Schema description coverage is 100% and the parameter docs are detailed (depth semantics, artboard index, coordinate systems with an informative get_document_info pointer). The description adds nothing about parameters, so baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (tree structure of layers, groups, and objects), which is more than a tautology. However, it does not distinguish itself from close siblings like get_layers, get_groups, or get_document_info, leaving the agent to infer that this tool returns the combined hierarchy.

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 offers no when-to-use, when-not-to-use, or alternative-tool guidance. With siblings such as get_layers, get_groups, and find_objects available, an agent gets no signal about when this combined tree view is preferable.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context beyond that — no indication of whether it requires a selection, how large the result may be, or whether it errors when no target is given.

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

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

It is only six words with no punctuation or structure, which is under-specification rather than effective conciseness. There is no front-loaded scope or qualifier to make the brevity useful.

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 and no annotations beyond the safety profile, so the description should carry the burden of explaining return content and scope, which it does not. For a query tool with a filtering parameter and a coordinate-system mode, the agent has no idea what a result set looks like or how it relates to the current selection.

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

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

Schema description coverage is 100%, including a detailed enum explanation for coordinate_system, so the schema does the heavy lifting and the baseline is 3. The description adds nothing about target, selection_only, or coordinate_system beyond what the schema already states.

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

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

States a verb ('Get') and a resource area ('effect and appearance information'), so the agent knows this is a read for styling/effects data. However, 'effects' and 'appearance' are broad, undefined terms, and the description gives no differentiation from nearby siblings such as list_graphic_styles, get_overprint_info, or get_separation_info. It is adequate but leaves the agent guessing exactly what 'effects' 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?

There is no when-to-use guidance, no statement of what scope it reads (whole document vs. selection vs. a single object), and no mention of any alternative tool. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is fully covered. The description adds one useful behavioral fact — that the result covers clipping masks and compound paths, not just plain groups — but says nothing about traversal depth defaults, output shape, or empty-result 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?

A single short sentence with no filler, and the retrieval scope is front-loaded. It is efficient, though arguably so terse that key routing information was cut rather than compressed.

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?

All three parameters are optional, the schema fully documents them, and annotations cover the safety profile, so the definition is callable as-is. Still, with no output schema, the description leaves the return structure and the distinction from get_document_structure/get_layers unstated.

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

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

Schema description coverage is 100%, and the coordinate_system parameter in particular carries a detailed explanation, so the schema does the heavy lifting here. The description adds no syntax, filtering, or depth semantics beyond what the schema already documents, which is the baseline 3 case.

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 ('Get') and a concrete resource ('structure of groups, clipping masks, and compound paths'), so an agent knows it retrieves group hierarchy data. It does not, however, distinguish itself from nearby siblings like get_document_structure, get_layers, or get_path_items, which could plausibly return overlapping information.

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

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

There is no guidance on when to reach for this tool versus get_document_structure, get_layers, or ungroup_objects, and no stated prerequisites or exclusions. The agent must infer usage purely from the name and the retrieval scope implied by the sentence.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond the name — no scoping behavior, no indication of what is returned or how guides relate to artboards/coordinate systems, which the parameter schema hints at but the description never connects.

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

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

It is short and front-loaded, but the brevity comes from under-specification rather than efficiency. The one sentence is too thin to earn its place as a tool description.

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

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

This is a low-complexity read tool, so the bar is not high, and annotations plus a well-documented single parameter cover most structural needs. However, the description leaves the fundamental question — what data about which guides, and in what coordinate context — unanswered, and there is no output schema to compensate.

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

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

Schema description coverage is 100% and the single optional coordinate_system enum is documented in detail, including auto-detection rules and a cross-reference to get_document_info. With the schema carrying the full burden, the baseline of 3 applies; the description contributes no additional parameter meaning.

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

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

"Get guide information" essentially restates the tool name and title. It never clarifies what a "guide" is in this context (Illustrator ruler/guide objects vs. style/brand guidelines), leaving the agent to infer from siblings like get_document_info. The verb is specific but the resource is 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?

No when-to-use guidance, no prerequisites, no mention of alternatives such as get_document_info, get_document_structure, or get_artboards. Nothing tells the agent under what circumstances this tool is the right call.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that: it does not say what information is returned, whether the coordinate system matters, or what include_print_info diagnostics 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?

A single seven-word phrase with no filler, and the subject matter is front-loaded. It is efficient, though it reads as an under-specified fragment rather than a complete statement of 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?

There is no output schema, so the description carries the burden of explaining what 'image information' actually contains — dimensions, placement, link status, color space, etc. It never does, and it also omits any note that include_print_info only applies to embedded raster images, leaving the agent unable to predict the response.

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

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

Schema description coverage is 100%, and the coordinate_system enum and include_print_info flag are thoroughly documented in the schema, including the get_document_info cross-reference. Baseline 3 is appropriate since the description contributes no additional parameter meaning.

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

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

States a specific verb (Get) and resource (embedded and linked image information), so the agent knows it retrieves image metadata rather than modifying images. It does not explicitly differentiate itself from siblings like manage_linked_images or find_objects, but the resource scope is clear enough to route correctly.

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

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

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative (manage_linked_images) for linked-image operations. The agent must infer that this is a read/inspection step from the name alone.

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

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

Annotations already declare the full safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description carries a lighter burden. It adds only the 'tree' output shape, which is useful but thin; with no output schema it could have disclosed the node shape, depth, or handling of hidden/locked layers.

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 front-loaded sentence with no filler, which is efficient. It is arguably under-specified rather than concise, but nothing in the text wastes the agent's attention.

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 three optional, fully documented parameters and annotations covering safety, the description is minimally sufficient. The remaining gap is the return structure: with no output schema, 'as a tree' does not tell the agent what fields a layer node contains or how include_items/include_sublayers change the shape.

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

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

Schema description coverage is 100%, and the coordinate_system parameter is documented in exceptional detail in the schema (enums, auto-detection rule, axis orientation, cross-reference to get_document_info). The description adds nothing beyond the schema, so the baseline 3 is appropriate.

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

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

States a clear verb and resource ('Get layer structure') plus the output shape ('as a tree'), so the agent knows it returns a hierarchical view rather than a flat list. It does not distinguish itself from overlapping siblings such as get_document_structure, get_groups, or manage_layers, leaving the choice 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?

There is no guidance on when to use this tool versus get_document_structure, get_groups, or manage_layers, and no mention of prerequisites or conditions. The only implied usage is 'when you need layer structure', which the name already conveys.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context beyond that. It usefully discloses that the tool performs analysis (K100/rich black detection and intent classification) rather than merely echoing raw flag values, which is substantive behavioral information not present in any structured field.

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 verb and resource, with zero filler. It is tight and appropriately sized for a zero-argument query tool.

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 input parameters, no output schema, and full annotation coverage, the description only needs to say what the tool returns and why it is useful. It conveys the analysis performed but leaves the meaning of 'intent classification' and the shape of the result unstated, a minor gap given the absence of an 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?

The tool takes zero parameters, so there is no schema surface for the description to compensate for. The baseline of 4 applies; nothing is contradicted or left ambiguous.

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 pairs a specific verb ('Get') with a specific resource ('overprint settings') and adds what is computed ('K100/rich black detection and intent classification'). It is clearly distinct from neighbors like get_separation_info or preflight_check, though it never explicitly names which sibling it is not.

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

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

There is no when-to-use context, no prerequisites, and no mention of alternatives such as get_separation_info or preflight_check, which an agent might reasonably confuse with this one. Usage must be inferred entirely from the tool name.

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 a genuinely useful output-semantics caveat (fill/stroke exclude per-attribute opacity; use item-level opacity instead), which is value beyond annotations, but it says nothing about the shape of returned data, pagination, or cost.

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, purpose front-loaded and the caveat immediately after. No filler, redundancy, or repetition of schema/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?

There is no output schema, so the description should carry more of the return-value burden for a data-extraction tool. The opacity note is a helpful hint but the description does not convey the structure of the returned path/shape data, leaving an agent to infer the response shape.

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

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

Schema description coverage is 100%, including a detailed enum explanation for coordinate_system, so the schema carries the parameter burden. The description adds no parameter-level meaning of its own, which matches the baseline 3 when the schema already documents everything.

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

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

The description states a clear verb+resource ('Get path and shape data'), which is more specific than a bare restatement of the name. However, it offers no differentiation from siblings like find_objects, get_layers, get_document_structure, or get_groups, so an agent cannot easily tell which extraction tool to pick from purpose alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The only guidance is an output caveat about opacity, not a condition for selecting this tool over neighbors like find_objects or get_layers.

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, closed-world, so the bar is lower. The description nevertheless adds genuine behavioral context: no script is dispatched to Illustrator, no Computer Use, and the important constraint that uncertain executions must not be replayed. It omits return-format detail, but the safety profile is well covered.

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

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

It is short and front-loads the core action, but it reads as three disconnected fragments ('No Computer Use' especially) with choppy structure. It is concise without being cleanly organized.

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

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

With no output schema and no parameters, the description carries the burden of conveying what state is returned, but it never explains the shape or meaning of the returned policy/ownership information. Adequate for a no-param read tool, but the return behavior is left unstated.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No parameter guidance is required.

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 verb (Read) and two resources (background policy, cross-process execution ownership), and distinguishes itself from run_script via 'without sending a script to Illustrator.' However, the phrasing is abstract and jargon-heavy, and it does not map cleanly onto the tool name 'get_runtime_status,' leaving the actual purpose somewhat opaque.

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

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

It implies usage through 'without sending a script to Illustrator' and the caution 'An uncertain execution must not be replayed,' suggesting this is a pre-check tool. But it names no explicit alternative (e.g., recover_execution, a sibling clearly in scope) and gives no clear when-to-call 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely behavioral fact: the result depends on external live selection state (the 'currently selected' objects), but says nothing about return shape or behavior when nothing is selected.

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 front-loaded sentence with zero filler. It is efficient, though 'detailed information' is vague enough that the brevity shades into under-specification.

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 is the only place return values could be characterized, and 'detailed information' leaves the agent guessing what fields come back. For a one-parameter read tool this is passable but leaves a real gap.

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

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

Schema description coverage is 100%, and the coordinate_system parameter is documented in the schema far beyond anything in the description (enum values, auto-detection rules, Y-axis conventions). Baseline 3 applies; the description contributes nothing additional.

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?

Clear specific verb+resource: 'Get detailed information about the currently selected objects'. It is the only sibling concerned with the live selection (versus select_objects, find_objects, get_document_structure), but it never names or contrasts those siblings explicitly.

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

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

No when-to-use, prerequisites, or alternatives are stated. An agent must infer that this reads the active Illustrator selection rather than querying objects by criteria; nothing routes it away from find_objects or select_objects.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds what is returned (plate types plus usage counts), but says nothing about output format, cost, or scope limits, which keeps it at an adequate rather than rich level.

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 front-loaded sentence that names the operation and then enumerates the returned data. Every clause earns its place, with no filler or redundancy.

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

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

For a zero-parameter, read-only, idempotent getter with no output schema, the description carries the burden of telling the agent what comes back, and it does so at a high level (process plates, spot plates, usage counts). Only the exact return shape and any pagination/limits are unstated, which is a minor gap given the simplicity.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies the call is context-driven (operates on the current document) without needing parameter detail.

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 (Get) and resource (color separation information) and enumerates the returned content: CMYK process plates and spot color plates with usage counts. This clearly separates it from siblings like get_colors (color inventory) and get_overprint_info (overprint settings), though it does not explicitly name those alternatives.

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

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

The description gives no when-to-use guidance, no prerequisites, and does not point to or away from related siblings such as get_colors, get_overprint_info, or preflight_check. Usage is only inferable from the content it returns; an agent gets no explicit routing signal.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on what is returned, whether definitions and instances are combined or separate, or whether results are document-scoped.

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 phrase is front-loaded and free of waste, but it is underspecified rather than genuinely concise — it is short only because it omits scope and return information an agent needs.

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 description should carry the burden of describing what comes back; it only vaguely signals 'definitions and instances'. The single well-documented parameter and strong annotations keep this from being inadequate, but the return behavior remains under-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 100% and the single optional coordinate_system parameter has a thorough enum explanation in the schema itself. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

The description names a verb ('Get') and a resource ('symbol definitions and instances'), which is more than a tautology of the title. However, it never clarifies scope (all document symbols vs. selection) or what a 'symbol' means in this context, so an agent cannot confidently distinguish it from siblings like place_symbol without opening 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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as find_objects or place_symbol. The agent is left to infer usage entirely.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower; the description adds real value with the version-dependent caveat that paragraph leading/autoLeading may return 0 in some ExtendScript versions. It also discloses the unit convention for kerning values (1/1000 em), which prevents misreading the output.

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

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

Front-loaded with the core purpose, followed by a compact enumeration of returned sections and two caveats; no filler sentences. It is somewhat dense, but every clause (attribute groups, unit convention, version caveat) conveys information an agent needs.

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 description usefully pre-describes the return shape (runs, kerning pairs, paragraph attributes, cssHints) and flags a known data-quality caveat. It leaves minor gaps, such as how to source the uuid and what happens on a missing/invalid frame, but is largely sufficient for a read-only two-parameter tool.

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

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

Schema description coverage is 100% and the coordinate_system enum is fully explained inline, including its default auto-detection rule, so the schema carries the parameter burden. The description adds nothing about uuid or coordinate_system; the '1/1000 em' note describes returned data rather than an input. Baseline 3 applies.

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

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

States a specific verb and resource ('Get detailed text frame attributes') and enumerates the payload (per-character runs, kerning pairs, paragraph attributes, cssHints), which separates it from the coarse-grained list_text_frames sibling by granularity. It never names that sibling explicitly, so an agent must infer the list-vs-detail split.

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 contains no when-to-use or when-not-to-use guidance, no prerequisites for obtaining the uuid, and no routing to alternatives such as list_text_frames or check_text_consistency. The only operative instruction ('Call get_document_info to check which system is active') lives in the schema, not the description.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the description is free to add operational context — and it does, disclosing the stacking-order semantics and that execution happens in background mode without invoking Computer Use. It stops short of saying what happens to the source objects' layer membership or whether a new group object is returned.

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

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

Three tight sentences with the core action front-loaded and no filler. The ordering sentence is mildly redundant with the schema, but the background-mode caveat is genuinely load-bearing context for an agent choosing between this and run_script.

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 covers ordering and execution mode but omits what the caller gets back (a new group UUID?) and any side effects on layer membership of the grouped objects. Adequate but with a clear gap for a write operation.

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

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

Schema description coverage is 100%, so the ordering rule and the clipped/mask behavior are already documented in the schema. The description's ordering sentence largely restates the uuids schema text, adding no new syntax or constraints beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Group multiple objects into a single group'), which is unambiguous. It does not explicitly contrast itself with the nearest siblings (ungroup_objects, duplicate_objects, set_z_order), though the name makes the inverse relationship obvious.

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

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

No when-to-use guidance and no prerequisites are given. It never says how this differs from set_z_order, duplicate_objects, or manage_layers, nor does it say what state the objects must be in (selected, same layer, ungrouped) before calling.

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, and the description adds real behavioral context beyond them: compound paths and holes are retained, open source PDFs are rejected, and coordinates are in native document points. It does not say whether the write is reversible or what happens to pre-existing target content, but the added detail is substantive.

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 tight sentences, front-loaded with the core action, then constraints and units. No filler or restatement of the tool name.

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

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

For a destructive, multi-parameter import into an existing document, the description covers the mechanical result well but leaves gaps: no mention of required open-document state as a prerequisite, no undo/permission expectations, and several parameters undocumented. 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% across 6 parameters, so the description carries the full documentation burden. It clarifies that fit_bounds are in native document points and that pdf_path must be an outlined vector PDF, but page, group_name, target_layer_path, and document_path semantics are never explained.

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: copy actual vector paths from a prepared outlined PDF into an open target document. It also carves out a distinct niche versus siblings like place_image (raster) and import_svg_as_editable (SVG), so an agent can differentiate without opening other schemas.

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

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

Gives clear preconditions ('prepared outlined vector PDF', target document must be open) and exclusions ('No clipboard, linked PDF or raster substitute', rejects source PDFs already open). It stops short of naming the alternative tool to use for raster or linked placement, 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 mark this as a non-read-only, non-idempotent mutation but say nothing about mechanism. The description adds real behavioral context: it opens the SVG as a temporary document, duplicates contents, and closes the source, plus runs without activating Illustrator by default and never invokes Computer Use. This is far beyond what the structured fields 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 tight sentences: purpose/outcome first, then the internal mechanism, then the sibling alternative and invocation constraints. Every sentence earns its place and the most decision-relevant facts are 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?

No output schema exists, but for this mutation tool the description covers purpose, mechanism, alternative, and execution environment. Parameters are fully covered by the schema, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters (including the coordinate_system enum and fit_to_artboard semantics). The description adds no per-parameter detail, so baseline 3 applies.

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

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

States a specific verb (Import), resource (SVG file), and crucial outcome qualifier (editable Illustrator paths/text/groups, NOT a linked image). It explicitly distinguishes the 'editable' behavior from place_image, so an agent can route correctly.

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?

Directly names the alternative and the condition: 'Use this instead of place_image for SVG.' It also clarifies that it works in background mode without invoking Computer Use, removing ambiguity about invocation style.

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, so the safety profile is fully covered by structured data. The description adds a genuinely non-annotated operational fact — that the call works without an open document — which changes how an agent sequences it relative to document-dependent tools.

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 zero filler, and the core purpose is front-loaded before the operational note. Nothing could be removed without losing 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?

A zero-required-parameter, read-only enumeration tool with full schema coverage and complete annotations needs little more than this. The only minor gap is that no return shape is described and there is no output schema, so an agent cannot anticipate the result format (e.g., truncation behavior under the limit).

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

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

Schema description coverage is 100%: both limit and filter are documented in the schema with their semantics and default. The description adds no additional parameter meaning, so this is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (fonts) scoped to Illustrator, which is unambiguous and distinguishable from other 'list_*' siblings like list_text_styles and list_graphic_styles. It does not explicitly name or contrast a sibling, which would be needed for a 5, but no sibling overlaps its 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?

Usage is implied rather than stated: 'List fonts available in Illustrator' plus the note that no open document is required tells the agent this can be called as a standalone query. There is no guidance on when to prefer this over alternatives or how the limit/filter options should be used to scope the call.

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, idempotent, non-destructive and closed-world behavior, so the safety profile is fully covered. The description contributes only the 'active document' scope constraint and says nothing about return format, ordering, or cost — adequate but not additive.

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 front-loaded sentence with no filler; every word earns its place.

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

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

For a trivial zero-arg read tool with annotations covering safety, this is nearly sufficient, but there is no output schema and the description never indicates what a 'graphic style' entry contains (name, id, index), leaving the return shape unknown to the 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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 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?

Specific verb ('List') plus resource ('graphic styles') and scope ('in the active document') make the operation immediately clear. It does not, however, distinguish itself from the sibling list_text_styles or explain why an agent would pick this over get_document_structure.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as list_text_styles or apply_graphic_style. Usage is only inferable from the verb.

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 establish the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lowered. The description adds useful context about the returned granularity ('summary-level') and the lean contents-only mode, but says nothing about default return fields or result size.

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 compact sentences with the purpose front-loaded and no filler. The capability sentence is slightly list-like but still earns its place by flagging the sort and contents-only modes.

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 description carries some burden for describing return shape, and 'summary-level information' is vague about which fields come back in the default mode. Annotations cover the safety profile, so the remaining gap is 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 100% and every parameter, including both enums and the coordinate-system auto-detection rule, is documented in the schema itself. The description only echoes sort, pagination, and contents-only mode, adding no syntax or default-value detail beyond the schema.

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

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

States a specific verb and resource ('List text frames') plus the scope of data returned ('summary-level information'). That scope phrase implicitly separates it from get_text_frame_detail, but it never names the sibling, so the distinction is left 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 second sentence lists capabilities (sort, pagination, contents-only mode) rather than conditions for choosing this tool. Nothing says when to prefer this over get_text_frame_detail or find_objects, and there are no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds only the 'active document' scoping detail and says nothing about return shape or whether style definitions (not just names) are included; with annotations doing the heavy lifting, a 3 is appropriate.

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 declarative sentence with no filler, front-loading the verb and the resource. Nothing in it is redundant with the title or annotations.

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

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

For a no-parameter, read-only listing tool with no output schema, stating the resource and its scope is enough for an agent to call it correctly. Minor gap: it does not say what identifiers or detail level each listed style carries, which would matter for chaining into apply_text_style.

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

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter semantics to explain. Baseline of 4 applies; the description correctly does not invent parameter discussion.

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?

Specific verb ('List') plus a precisely bounded resource ('character and paragraph styles in the active document'), which implicitly separates it from siblings like list_graphic_styles and list_fonts. It stops short of explicitly naming those alternatives, so the differentiation is inferential rather than stated.

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 when-to-use guidance, no prerequisites, and no pointer to related tools (apply_text_style, list_graphic_styles). The 'active document' scope is the only contextual constraint, and it is a statement of scope rather than usage advice.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely new context ('runs without activating Illustrator in default background mode; never invokes Computer Use'), but it never says which sub-action is destructive, that removal is irreversible, or how a failed run is recovered. Useful but partial, so a 3.

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

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

Two sentences, front-loaded with the operation list, no filler or repetition of the title. The second sentence is slightly tangential but carries real execution-mode information, so it earns its place; structure is efficient overall.

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

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

This is a 6-action tool with 7 parameters, a nested rect object, and no output schema, so the description carries a lot of coordination burden. The action enum and schema fields cover most per-action needs, but the description gives no mapping of which parameters belong to which action, no statement of what each action returns, and no routing to get_artboards for inspection. Adequate but with clear 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 100%, so the schema already documents every parameter, including the per-action conditional requirement on index and the constraints on rows_or_cols. The description adds no parameter-level meaning beyond the schema, making the baseline 3 correct.

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

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

The description opens with a specific verb ('Add, remove, resize, rename, fit, or rearrange') applied to a concrete resource ('artboards'), and the enumerated operations match the action enum. This clearly separates it from the sibling read-only get_artboards. It stops short of naming that sibling or otherwise explicitly disambiguating, keeping it at a 4.

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

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

There is no guidance on when to use this tool versus alternatives such as get_artboards or create_document, and no stated prerequisites. The condition that index is required for four of the six actions exists only in the schema, not in the description, so an agent gets no usage framing here.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write profile is covered. The description usefully adds that CSV headers auto-bind to matching object names and that it runs in background mode without invoking Computer Use, but it never warns that create/apply/bind actions mutate the document.

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

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

Three sentences, front-loaded with the operation list and no filler. The execution-mode note is placed last where it belongs, though the opening list slightly duplicates the action enum.

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 eight-action multiplexer with no output schema, the description maps only the main operations and leaves 'export' unmentioned and per-action prerequisites unstated. Annotations carry the safety profile, but the agent gets only a partial action map.

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

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

Schema description coverage is 100% and the 'dataset_name_prefix' note ('If omitted, first column value is used') already lives in the schema. The description's CSV auto-binding sentence adds marginal value but mostly restates schema-level behavior, so a baseline 3 fits.

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 specific verbs and resources ('List variables/datasets, apply or create datasets, bind variables to objects, import CSV/XML'), so the domain is unmistakable. It covers most of the action enum but omits 'export', and it does not distinguish itself from overlapping siblings like 'export'/'import' by 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?

There is no when-to-use guidance and no exclusions. With sibling tools literally named 'export' and 'import' that overlap with this tool's import/export actions, the agent receives no help deciding which entry point to pick.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false. The description adds no behavioral context beyond restating the action list, such as which operations are destructive, what delete removes, or whether layer changes can be undone.

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

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

The description is a single, front-loaded sentence with no redundant or filler text. Every word contributes to summarizing the tool's operations.

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 schema fully documents parameters and annotations cover the safety profile, so the description is minimally adequate for invocation. However, it gives no guidance on choosing this multi-action tool over related siblings or on action-specific behavior, leaving a clear contextual gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including action-specific requirements like new_name for rename and above for add. The description adds no parameter syntax or action-to-parameter mapping beyond what the schema provides, making the baseline 3 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 names the resource (layers) and enumerates specific operations, so the tool's purpose is immediately clear. However, it does not distinguish this management tool from sibling read/list or move-layer tools such as get_layers or move_to_layer, which the rubric requires for 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?

The description lists available actions but does not state when to use this tool versus alternatives like get_layers, move_to_layer, or duplicate_layer_tree. Usage is only implied by the action list, and there are no exclusions or selection criteria.

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 destructiveness, but the description goes further: it states that embed converts a PlacedItem to a RasterItem, that the original UUID becomes invalid, and that a new UUID is returned. It also discloses runtime behavior (background mode, no Illustrator activation, no Computer Use), which is context annotations cannot express.

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 with zero filler; the core action is front-loaded, followed by the destructive identity-change consequence, then the runtime note. Every sentence carries information an agent needs.

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 description compensates by explaining the returned UUID and the invalidation of the original one, plus the execution-mode caveat. For a 3-parameter destructive mutation tool this covers what an agent must know before calling.

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

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

Schema description coverage is 100%, so uuid, action, and new_path are already documented in the schema, including the 'required for relink' constraint. The description adds little parameter-level detail beyond that, so the baseline of 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 specific verb pair (relink/embed) and a precise resource (placed/linked image), and it is clearly distinct from neighboring tools such as place_image, replace_masked_image, and get_images. An agent can identify the operation without opening 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?

It explains the effect of the 'embed' action but gives no explicit condition for choosing 'relink' over 'embed', nor any prerequisite/when-not guidance (e.g., when a relink is preferable to re-placing). Usage is implied by the action semantics 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 declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: it runs without activating Illustrator in background mode and never invokes Computer Use, which is useful execution-model disclosure. It stops short of stating permissions or what deletion does to in-use swatches.

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

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

Two tight sentences with the operation set front-loaded and the execution-model note following. Every sentence earns its place, with no redundancy, though it is borderline terse for a mutation tool.

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

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

For a 3-parameter mutation tool with a fully described schema and no output schema, the description covers the actions and the execution model adequately. Remaining gaps (permissions, effect on in-use swatches, response shape) are minor against the destructiveHint annotation and complete 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 100%, so all three parameters and the color union are documented in the schema itself. The description adds no syntax, format, or constraint detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb set (add/update/delete) and resource (swatches in the active document), which an agent can map directly to the action enum. It does not, however, differentiate itself from related siblings like replace_color or get_colors, so ambiguity remains about when swatch manipulation is the right primitive.

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 enumerates the operations available but gives no explicit when-to-use guidance, no conditions for choosing add vs update vs delete, and no pointer to alternatives such as replace_color for restyling existing artwork. Usage is implied only through the action enum.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the mutation risk and non-idempotency are covered structurally. The description adds genuinely new operational context — background execution without activating Illustrator and no Computer Use invocation — but does not disclose what is destroyed or how partial failures behave.

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

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

Two sentences, front-loaded with the purpose, with no wasted wording. The execution-mode clause is secondary but relevant enough to justify its place for a destructive tool.

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 broad mutation tool with fully documented parameters and clear destructive annotations, the essentials are recoverable from structured fields. The description is nonetheless thin on when to prefer it over other mutating siblings and on failure/mutation scope, which matters given the many parallel mutation tools.

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

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

Schema description coverage is 100%, so the schema already documents uuid, the nested property object (fill, stroke, rotation_mode, etc.), and coordinate_system semantics thoroughly. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

"Modify properties of an existing object" gives a specific verb and resource, so the agent knows this is an in-place mutation of an existing object rather than a creation or deletion. However, it does not differentiate from siblings that also mutate object attributes (replace_color, move_to_layer, apply_graphic_style, set_z_order), leaving the agent to guess which mutation path applies.

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

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

There is no statement of when to use this tool versus alternatives, nor any prerequisite (e.g., the object must already exist, how to obtain the uuid, that find_objects or get_selection should precede it). The second sentence addresses execution mode, not usage 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds useful behavioral context beyond annotations: it runs in default background mode without activating Illustrator and never invokes Computer Use.

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