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

With no annotations, the description carries the behavioral burden and does it well: it discloses wire re-encoding, newline restoration, forbidden characters, the 8 KB cap, and path slash conversion. It stops short of discussing reversibility or failure modes, but the append operation is reasonably clear.

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

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

The description is compact, front-loaded with purpose, then uses the remaining sentences for constraints and guidance. Every clause earns its place, and the wire-format constraints are grouped logically.

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

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

For a two-parameter additive tool with no required parameters and no output schema, this description is effectively complete. The agent knows what to provide, how to provide it, which option to prefer, and the hard constraints that could cause failures.

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%, but the description adds substantial meaning beyond the schema: mutual exclusivity of 'path' and 'obj_data', the preference rule, inline OBJ character restrictions, the 8 KB limit, and newline handling. This is far beyond the baseline.

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

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

The description opens with a precise verb and resource: 'Append geometry to the current project', then specifies the two allowed input sources. This makes the tool distinct from export/import siblings and clearly communicates what it does.

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 strong within-tool guidance: exactly one of 'path' or 'obj_data' must be supplied, and 'path' should be preferred for anything non-trivial. It does not explicitly contrast this tool with ap_import_asset, but the usage context is clear enough.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so thoroughly: it reveals the real performance cost, names the underlying call (iron_delay_idle_sleep()), explains the effect on rendering/focus behavior, and warns that disabling interrupts request processing. This is exemplary transparency for a state-changing tool.

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

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

The description is concise but information-dense. The core action is front-loaded, followed by the cost, the recommended usage, and a critical warning. Every sentence earns its place and none is redundant with 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 one-parameter toggling tool with no output schema, the description is complete. It covers what the tool does, when to use it, what the side effects are, and what to be careful about. An agent can safely and correctly invoke it based on this description alone.

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

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

The input schema already fully describes the single boolean parameter, so the baseline is 3. The description adds meaningful semantics beyond the schema by tying the parameter to practical consequences: enabled means full-rate polling, disabled means idling and losing request reading. This lifts it above baseline.

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

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

The description opens with a specific verb and resource: 'Turn the bridge's per-frame polling on or off.' It clearly identifies what state is being changed and is distinct from the sibling tools, which mostly deal with painting, project management, or object operations.

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

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

The description explicitly says when to disable the bridge ('Disable it when no agent is working'), explains why it is normally enabled (remote control of a background window), and includes a strong warning that disabling stops request reading, making this the last tool that will work until manual re-enable. This gives clear operational guidance beyond merely stating what the tool does.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It fully discloses that no round trip is made, what data is reported (spool directory resolution, heartbeat existence, clock progression, versions, project, queue depth), and that it produces a plain-language diagnosis plus next step. This is exemplary transparency.

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 information-dense but tightly structured: an opening purpose, a complete list of reported diagnostics, and a direct invocation instruction. Every clause adds useful guidance and the most important usage instruction is placed at the end for emphasis.

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

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

For a diagnostic tool with no annotations and no output schema, the description is unusually complete. It covers what the tool does, what it returns, why it is reliable during transport failures, what counts as the only valid liveness test, and exactly when to call it first.

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 single parameter is fully described in the input schema, including its default value and behavioral effect, and schema description coverage is 100%. The tool description itself does not add param-level meaning, but per the baseline rule, high coverage makes 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 opens with a specific action ('Diagnose the connection to ArmorPaint') and then enumerates the exact diagnostic outputs. It distinguishes itself from likely siblings like ap_ping by stating that the advancing heartbeat clock is 'the only valid liveness test' and by clarifying that this tool is answered server-side without a round trip.

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 final sentence gives an explicit, unambiguous usage rule: 'Call this FIRST whenever any other tool reports a transport error.' It also explains why this is the right choice by noting it works even when the bridge is otherwise failing, giving the agent a clear decision rule.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that the result is persisted only on .arm save, cannot be read outside ArmorPaint, is captured from the already-drawn frame, may include the UI overlay, and cannot reproduce ArmorPaint's two-frame settle.

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 relatively long but every clause carries essential caveats (persistence, visibility, one-frame timing, UI overlay, patch requirement). It is front-loaded with purpose before the caveats, though it could be tightened slightly without losing meaning.

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

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

For a tool with no annotations and no output schema, the description covers the core use case, the alternative tool, the persistence model, the platform requirement, and the rendering timing limitations. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100%: both width and height have clear 'Capture width/height in pixels' descriptions and defaults. The tool description adds no parameter-specific behavior, 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-resource-target statement: 'Capture the 3D viewport into the project as a packed texture asset.' It clearly differentiates from the sibling ap_capture_viewport by positioning that tool for actually viewing the result.

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

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

It gives an explicit conditional: use this on stock ArmorPaint when pixels should land inside the project, and use ap_capture_viewport when the goal is to actually see the viewport, noting the optional viewport patch requirement. No inference is required.

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

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

With no annotations provided, the description carries the transparency burden, and it does well: it discloses the dependency on the viewport patch, the unsupported-code failure mode, and the fallback behavior. It stops short of specifying other side effects such as overwrite semantics or exact response shape on success, which keeps it from a 5.

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

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

The description is front-loaded with the primary purpose and then adds a single, dense caveat paragraph covering compatibility and fallbacks. Every sentence contributes information an agent needs; there's no fluff or repetition.

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

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

Given there is no output schema, the description usefully explains that success returns an image and that include_image=false returns just the path, and it covers the unsupported-build case. It does not describe the broader response envelope, but for a capture-and-return-image tool this is reasonably 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 100%, so the schema already documents all four parameters including defaults and the include_image behavior. The description adds no additional parameter-level meaning beyond confirming the output is a PNG image, which matches the baseline for full schema coverage.

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

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

The description names a specific operation ('Capture the shaded 3D viewport to a PNG file') and clarifies the return value ('return the image so you can look at your own work'). It also differentiates the tool from nearby siblings by naming the fallbacks and their limitations.

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

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

The description explicitly states the prerequisite (optional viewport patch) and what happens on a stock build ('unsupported'), then names the two fallback alternatives with the precise conditions for each (in-project only vs real flat files). This gives an agent clear routing guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly discloses that writes cannot be read back and are intended only for human visibility. It does not detail the exact visible output or whether the call returns a status, but for a simple write-only console tool, this is sufficient context.

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

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

Two concise sentences with no filler. The core action is front-loaded, followed immediately by the critical write-only caveat. 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?

This is a simple two-parameter tool with no output schema. The description fully covers purpose, behavioral constraints, and appropriate usage context. An agent has enough information to call it correctly without additional explanation.

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

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

Schema coverage is 100%, so the schema already documents both 'text' and 'level' including the enum values and default. The description adds minimal parameter-specific meaning beyond the schema, mainly framing text as a 'line.' The baseline 3 is appropriate because the description does not need to compensate for missing schema information.

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

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

The description states a specific action and resource: 'Write a line to ArmorPaint's own console.' It also clarifies the write-only nature, which distinguishes it from any potential read/console-logging tool. This is far more informative than a generic 'Write to console'.

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 explicitly says when to use it: 'for leaving a trail for the human.' It also states when not to use it: 'not for logging you intend to read.' It does not name alternative sibling tools like ap_show_message, but the when/when-not guidance is strong enough for an agent to select it appropriately.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the general side effect (writes a .arm file) and the scope (active material), which is useful. However, it does not mention whether existing files are overwritten, whether directories must exist, or what happens if no material is active.

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 that names the action, the target, and the output format without any filler or repetition. It is appropriately sized for the tool's low parameter complexity.

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

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

The tool is simple, with one well-documented parameter and no output schema, so the core invocation is clear. However, the absence of sibling differentiation and behavioral details like overwrite behavior leaves an agent with gaps when deciding between this and related material-export 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?

The schema covers the single 'path' parameter fully with clear destination, format, absolute path, and slash-conversion details. The description adds little beyond the schema, but since schema coverage is 100%, 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 names a specific verb ('Export'), a specific resource ('the active material'), and a concrete output ('a reusable .arm material file'). It is clear and unambiguous, but it does not explicitly contrast with siblings like ap_export_material_bake or ap_export_textures, so it stops short of full sibling differentiation.

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

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

No guidance is given about when to choose this tool over ap_export_material_bake, ap_export_textures, or ap_material_save-related alternatives. The phrase 'active material' implies the precondition that a material is active, but no explicit when-to-use or when-not-to-use reasoning is provided.

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

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

There are no annotations, so the description carries full responsibility for behavioral disclosure. It mentions exporting images but does not explain side effects such as whether files are written, overwritten, or whether the scene/material is modified. This is a meaningful gap.

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

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

The description is concise: two sentences that directly state the purpose and an important exclusion. There is no unnecessary verbosity.

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

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

The description explains what the tool does but omits output details such as return values, file naming, or image formats. Given the lack of an output schema, this leaves some ambiguity about what the caller should expect after invocation.

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

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

The single parameter 'directory' is described in the schema, and the description adds useful detail about absolute paths and forward slashes, including that backslashes are converted. This is sufficient for the parameter.

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

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

The description clearly states the action: bake the active material onto a plane and export the result as images. It also explicitly differentiates this from mesh map baking, which helps distinguish it from similar export or baking 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 a clear purpose and a negative usage note ('not mesh map baking'), but it does not explicitly state when to use this tool versus alternatives like ap_export_textures or ap_export_material. Some inference is required.

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

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

With no annotations, the description carries the behavioral disclosure burden. It genuinely adds value by revealing that '.obj' is automatically appended and that the caller must pass a path without the extension. It does not address overwrite or return behavior, but the most important call-affecting trait is exposed.

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, followed immediately by the single critical usage warning. There is no filler or redundant 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 one-parameter export tool with no output schema and no annotations, the description covers the output format and the most important input constraint. Minor details like overwrite behavior or return status are absent, but they are not needed to make a correct call.

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

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

The schema already documents the path semantics well: destination path without extension, absolute path, forward slashes, and automatic backslash conversion. The description adds little beyond restating the extension caveat, so a baseline score is appropriate given 100% schema coverage.

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

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

The description states a specific verb ('Export'), a specific resource ('paint geometry'), and a specific output format ('Wavefront OBJ'). This clearly distinguishes it from sibling export tools like ap_export_textures and ap_export_material.

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 resource and format make the intended use reasonably clear, but the description does not explicitly say when to use this tool instead of other export-related siblings, nor does it offer exclusions or alternative routes.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it delivers: it flags the disk side effect, the return value, and three non-obvious external-state dependencies — the last export-dialog name (falling back to 'untitled'), the active export preset for channel suffixes, and the UI-determined format/bit depth (8-bit PNG by default). The 'IMPORTANT LIMITS' block makes explicit that none of these are settable from a plugin, preempting agent misconceptions about controlling output files.

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 in a clear order: purpose, return value plus usage chain, then the caveats grouped under the 'IMPORTANT LIMITS' label. No filler; the dense final sentence is justified because each listed limit is a genuine gotcha. The structure front-loads the most decision-relevant fact (what the tool writes).

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 one-parameter tool with no annotations and no output schema, the description is remarkably complete: purpose, side effects, return value, output consumption, and all external-state dependencies are covered. The remaining gaps are minor — 'Returns the files found in the target directory afterwards' is ambiguous about whether pre-existing files are included, and directory-existence/overwrite behavior is unspecified. A genuinely helpful description with two small holes, hence a 4.

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

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

The schema already documents directory at 100% coverage ('Absolute path, forward slashes (backslashes are converted for you)'), so the baseline is 3. The description adds decisive extra meaning: 'directory' is a DIRECTORY, not a filename, and actual naming/format are governed by external UI state — a clarification that prevents the most likely misuse of the single parameter. This raises it to a 4; it stops short of 5 because the schema already handled the path syntax.

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 — 'Export the project's texture channels to real image files on disk' — and immediately differentiates from siblings by claiming to be 'the only binding in ArmorPaint's plugin API that writes images to disk.' An agent can distinguish it from export_mesh, export_material, and ap_read_image_file without opening schemas.

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

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

The claim that it is the only image-writing binding implicitly excludes alternatives, and the explicit chain 'feed one to ap_read_image_file to look at it' tells the agent how to consume the output. It lacks an explicit when-not-to-use statement or a direct comparison with sibling export functions (ap_export_material_bake, ap_export_mesh, ap_export_material), so it stops a point short of a 5.

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

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

With no annotations, the description carries full behavioral disclosure: it pushes an undo step, fails with no_project/bad_args if no layer is selected, has a side effect on the viewport, and is the only layer operation in the plugin API. This is far more than a basic summary.

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 key purpose is front-loaded in the first sentence, and every subsequent sentence contributes a distinct decision-relevant fact: visible effect, workflow order, error condition, and API uniqueness. The length is justified by the lack of annotations and schema details.

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

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

For a zero-parameter tool with no annotations and no output schema, the description covers behavior, prerequisites, failures, workflow placement, and alternatives. There is no meaningful information gap left for an agent to call it correctly.

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

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

The tool takes zero parameters and the schema is empty, so no parameter documentation is missing. The description adds meaning by identifying the implicit contextual inputs (selected layer and active material) and the failure mode when the layer state is absent.

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

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

The first sentence names a specific verb and resource: fill the selected layer with the active material and push an undo step. It further distinguishes itself from ap_material_update by stating that only filling/painting makes node-graph edits visible, and identifies itself as the only layer-bound API operation.

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

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

It gives an explicit working loop: ap_node_* edits -> ap_material_update -> ap_fill_layer -> ap_capture_viewport. It also warns that ap_material_update alone only recompiles the material and that nothing appears until fill/paint, so an agent knows exactly when this tool is required.

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

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

With no annotations, the description carries the transparency burden. It discloses that the operation is a read-only listing and that it executes against ArmorPaint's filesystem view, which may differ from this server. It does not address errors or output format, but the core behavior is transparent.

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

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

Two concise sentences with no filler; the key functional and contextual information is front-loaded.

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

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

For a one-parameter listing tool, the description is complete: it states the operation, the execution context, and the primary use case. No output schema is present, but the return concept is implicit in 'List a directory' and would not affect call correctness.

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

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

The input schema fully documents 'path' with absolute-path and slash-conversion details; the description adds the important nuance that the path is interpreted by ArmorPaint's process, which may live on another machine or container. This goes beyond the schema alone.

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

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

Clearly states it lists a directory and scopes it to the ArmorPaint process, which distinguishes it from server-side listing and from sibling FS tools like ap_fs_stat and ap_fs_mkdir.

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

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

Provides clear context by noting the remote/container filesystem and gives a concrete use case ('finding what an export actually wrote'), but does not explicitly contrast it with sibling tools or state when not to use it.

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

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

With no annotations provided, the description carries the full burden. It adds the useful behavioral nuance that the operation runs 'as the ArmorPaint process', implying its filesystem context. However, it does not mention error behavior, whether existing directories are tolerated, or whether parent directories are created.

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

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

A single sentence with no wasted words. The core action is front-loaded, and the example usage directly follows. Every element 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 one-parameter filesystem creation tool with no output schema, the description is sufficiently complete for an agent to invoke it correctly. The path format is fully documented in the schema, and the purpose is clear. Minor gaps like return value or existence handling do not materially hinder correct invocation.

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

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

Schema description coverage is 100%, and the path parameter is already well documented in the schema: absolute path, forward slashes, and automatic backslash conversion. The description adds no parameter semantics beyond the schema, 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?

Description states a precise verb and resource: 'Create a directory (as the ArmorPaint process)'. It clearly distinguishes this tool from filesystem read siblings like ap_fs_list and ap_fs_stat, and the example 'before an export' reinforces its purpose.

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

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

The description provides clear context: create a directory as the ArmorPaint process, e.g., before an export. It does not explicitly name alternatives or exclusions, but none are needed since the tool name and sibling set make the read-vs-write distinction obvious.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The wording 'Report whether' clearly frames the tool as an inspection/read operation with no side effects, and enumerates exactly what is tested. It does not cover error handling or permissions, but for a simple stat query this is reasonably transparent.

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

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

The description is a single, focused sentence with no filler. It front-loads the action and immediately lists the exact facts reported, making it easy for an agent to scan and understand.

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

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

The tool is simple with one parameter and no output schema. The description adequately conveys what the tool will tell the caller. It could mention the return shape or error behavior, but these are minor gaps for a stat-like 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%, and the schema already explains that the path must be absolute and use forward slashes. The description does not add significant new meaning to the 'path' parameter beyond restating the tool's purpose, so the baseline score 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 uses a specific verb ('Report') and resource ('path'), and clearly defines the three checks performed: existence, directory status, and absoluteness. This clearly differentiates it from sibling filesystem tools like ap_fs_list and ap_fs_mkdir.

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

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

The description implies when to use the tool—when path properties need to be verified—but it does not explicitly state alternatives or exclusions. There is no guidance like 'use ap_fs_list for listing directory contents' or 'prefer this before creating files.'

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is returned but does not explicitly state that the call is read-only, side-effect-free, or whether it requires an active ArmorPaint session. For a simple getter, the read-only nature is likely inferred, but error conditions and response behavior are not disclosed.

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

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

A single compact sentence that front-loads the core concept ('Application-level facts') and then lists the specific outputs. Every word earns its place, with no filler, redundancy, or unnecessary examples. It is concise while still being informative.

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, no-output-schema tool, the description gives a useful high-level summary of the return contents but stops short of specifying the exact field names or data types. It also does not mention any prerequisites such as the need for a live bridge connection or behavior if the application is unavailable. The list is sufficient to decide when to call it, but not fully complete for knowing exactly what to expect.

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

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

The tool has zero parameters, so the input schema is trivially complete (100% coverage). The description needs to add no parameter semantics since there are none to document. Baseline for a parameterless tool is 4, and the description doesn't introduce any confusion.

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

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

The description identifies the tool as returning application-level facts and enumerates specific data items: window title, size/position, data directory, and project format version. This clearly distinguishes it from sibling tools like ap_get_context and ap_project_get_info. It lacks an explicit verb like 'returns' or 'gets', but the tool name and the noun phrase 'Application-level facts' make the purpose 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?

The listed facts imply when to use this tool: when you need window information, the data directory, or the project format version. However, it does not explicitly contrast it with alternatives such as ap_get_context or ap_project_get_info, nor does it state when not to use it. Usage context is only implied, not explicitly guided.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the tool is read-only, enumerates what data is available, and explicitly excludes post-processing settings. It does not describe output formatting or error behavior, but for a parameterless config getter this is reasonably transparent.

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

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

The description is dense but purposeful: it front-loads the read-only nature and then provides a structured inventory of exposed preferences. The second sentence adds a valuable exclusion. It is not overly verbose relative to the amount of information conveyed.

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 parameterless getter with no output schema, the description is nearly complete: it lists the available preference categories and calls out what is absent. Minor gaps are the lack of explicit return-shape detail and failure conditions, but these are low-risk for this tool.

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

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

The tool has zero parameters and the schema is empty, so the baseline of 4 applies. The description does not need to explain parameter semantics because there are none; it instead focuses on what the returned configuration contains.

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

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

The description clearly identifies the tool as exposing application preferences that are readable from a plugin, and enumerates the specific preference groups included. This distinguishes it from sibling tools like ap_set_config (write counterpart) and ap_get_app_info (app-level info).

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

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

The description makes clear this is the read path for plugin-readable application preferences and explicitly lists what is included. It also says post-processing settings are not exposed, which prevents misuse. It does not explicitly name ap_set_config as the alternative for writing, but the read-only framing implies this boundary.

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

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

With no annotations provided, the description carries the full burden. It clearly labels the operation as a read and discloses an important limitation: the layer object itself is an opaque pointer and only selection status can be reported. This is genuine behavioral transparency beyond a field list.

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

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

Two sentences with no filler. The core purpose and field list come first, and the crucial layer-pointer caveat is placed in the second sentence. Every clause adds information the 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 and no annotations, this description is the sole source of behavioral and return-value knowledge. It provides a comprehensive enumeration of returned fields and flags the one inaccessible piece of data. Nothing essential is missing for calling this no-argument read tool correctly.

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

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

The tool has zero parameters, so there is no parameter semantics to document. The baseline of 4 applies; the description appropriately focuses on return content rather than parameters.

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

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

The description clearly identifies the action ('read') and the resource ('live painting context'), then enumerates the exact fields returned: active tool, brush properties, viewport mode, x-ray flag, layer/material selection state, and material name. This detailed scope differentiates it from sibling getters like ap_get_app_info and ap_get_config.

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

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

The phrase 'the workhorse read' implies this is the general-purpose context query, and the listed fields make the use case evident. However, there is no explicit guidance about when to prefer this over sibling tools such as ap_material_get_active or ap_select_tool, nor any when-not-to-use note.

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

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

With no annotations, the description carries the behavioral disclosure burden. 'Describe' communicates a non-mutating read operation and lists the returned data (name, visibility, transform). It does not state output format or possible absence of a main object, but for a no-argument getter the key side-effect-free behavior is clear.

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

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

A single sentence front-loads the action and resource, then lists the relevant details in a compact parenthetical. Every word earns its place; there is no repetition of the tool name or filler.

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

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

For a simple no-argument, read-only getter, the description is nearly complete: it names the target and the contents of the description. It does not explicitly say that the result is returned vs written to console, but 'Describe' plus the get_* naming makes this reasonably clear even without 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 has zero parameters and schema coverage is trivially 100%, so the description need not explain parameters. The baseline for zero-parameter tools is 4, and the description correctly focuses on what the tool returns rather than arguments it does not take.

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

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

The description states a specific action ('Describe') and resource ('main paint object'), and enumerates the exact attributes covered: name, visibility, and transform with location, rotation quaternion, and scale. The qualifier 'main' clearly differentiates this from sibling ap_get_object and the setter tools, so an agent can distinguish it without looking at 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?

The description establishes a clear use: retrieve information about the main paint object. It does not explicitly mention alternatives or exclusions, but naming 'main paint object' rather than generic 'object' gives enough context to avoid confusion with ap_get_object or transform/visibility setters.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It adds useful context: output is limited to visibility and transform, names are matched against paint objects, and enumeration is not supported. It does not cover error behavior if a name is not found, but 'Describe' sufficiently implies a read-only operation.

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

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

The description is two sentences, front-loads the core purpose, and the NOTE earns its place by conveying a critical limitation. There is no wasted wording.

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

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

For a one-parameter lookup tool with no output schema, the description explains what the tool returns, how lookup matching works, and the important enumeration limitation. An agent has enough information to invoke it correctly and interpret the result.

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

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

The schema already covers the single parameter with 100% coverage, so the baseline is 3. The description adds some context by saying names are matched against paint objects and used for lookup, but it does not add format, case-sensitivity, or failure semantics 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 clearly states a specific verb ('Describe') and resource ('a scene object by name'), and specifies what is returned: visibility and transform. It also distinguishes itself from ap_get_main_object by noting there is no enumerating binding, so an agent can tell which tool to use.

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 explicitly explains when this tool is appropriate: look up objects by name when they are paint objects, and it names the alternative (ap_get_main_object) for the main object case. This gives clear routing guidance with no inference required.

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

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

No annotations exist, so the description must carry behavioral disclosure. It does disclose that meshes 'replaces/adds' geometry and that routing depends on extension. It does not state whether imports overwrite existing assets, what happens on unsupported extensions, or whether an open project is required.

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

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

One tightly structured sentence with a colon separating the general action from the extension cases. Every word adds information; no filler.

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

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

For a single-parameter import tool, the description is nearly complete: path is handled and expected outcomes are enumerated. The only gap is lack of return-value/error behavior, but the operation's effect is observable in the project.

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

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

The only parameter, path, is already fully documented in the schema with absolute-path/forward-slash guidance. The description adds no parameter semantics beyond that, so the 100% schema coverage sets the baseline.

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

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

States a specific action ('Import a file'), the target project, and the three extension-routed outcomes. This makes it immediately distinguishable from more specialized siblings like ap_import_envmap.

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 extension-dispatch rule implies this is the right tool for image, mesh, and .arm files, but the description never explicitly contrasts it with ap_import_envmap or says when not to use it. An agent must infer the boundary from sibling names.

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

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

With no annotations, the description carries the full burden. It mentions reporting the envmap name, but it does not describe side effects on the scene, potential errors, or any other behavioral details beyond the basic import operation.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and output without unnecessary words.

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

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

The description provides enough context for a simple import tool: it specifies input type, the operation, and the reported output. However, it does not address error conditions or interactions with the project state, which could be relevant in a fuller context.

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

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

The parameter 'path' is described in the schema as 'HDR/EXR image. Absolute path, forward slashes (backslashes are converted for you).' The description in the tool text adds a clear detail about path format handling, which goes slightly beyond the schema description.

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

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

The description clearly states that the tool imports an HDR image as an environment map and reports the resulting envmap name. It also references the underlying script command, making the purpose unambiguous.

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

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

The description implies this tool is specifically for HDR environment map import, but it does not explicitly differentiate it from sibling tools like ap_import_asset or ap_set_envmap_params, nor does it state when to prefer this tool over alternatives.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose that the operation assigns an existing material and that lookup is by name, which is useful. However, it does not mention what happens if the object or material does not exist, whether the assignment replaces an existing material, or any side effects.

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

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

Two concise sentences with no redundant wording. The primary operation is front-loaded, and the important lookup detail about material naming is placed second.

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

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

For a simple two-parameter mutation tool, the description covers the core operation, the lookup mechanism, and the material naming convention. It is slightly incomplete around failure behavior and return values, but those are minor for this tool's 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 input schema already documents both parameters with 100% coverage, providing the baseline of 3. The description adds meaningful naming semantics beyond the schema by clarifying that the material name is the node-canvas name, which is essential for correct invocation.

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

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

The description uses a specific verb and resource: 'Assign an existing material to a scene object.' It clearly distinguishes this from sibling tools like ap_material_create, ap_material_select, and ap_material_delete by focusing on assignment to an object rather than creation, selection, or deletion.

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 practical context by explaining that both object and material are looked up by name, and that a material's name is its node-canvas name as reported by ap_material_get_active. This helps an agent know exactly how to supply the material argument, though it does not explicitly list when not to use the tool versus alternatives.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does state two key side effects: creating a slot and making it active. However, it does not mention what happens to the previously active material, whether a return value/handle is produced, or how name collisions are handled.

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 concise, front-loaded sentence that communicates both the creation and activation behavior with no filler or redundancy. 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?

The tool is simple with a single fully described parameter, so the description is mostly adequate. However, since there is no output schema, an agent is left unsure whether the tool returns the new material's identifier or other data, and no prerequisites are mentioned.

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

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

The input schema already fully describes the 'name' parameter with 'Name for the new material,' and schema description coverage is 100%. The description adds no extra parameter semantics beyond calling it a material slot, so a baseline score 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?

Describes a specific operation: creating a new material slot and activating it. This clearly distinguishes it from sibling material tools like ap_material_update, ap_material_delete, and ap_material_select, which handle different lifecycle stages.

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

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

No guidance is given about when to prefer this tool over alternatives, such as ap_material_update for modifying an existing material or ap_material_select for changing the active material. The intended context is only implied by the word 'create.'

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers. It explicitly discloses that the operation is irreversible, explains why (no undo/redo binding in ArmorPaint's plugin API), and states the single exception (user pressing Ctrl+Z in the app). This tells the agent exactly what gets destroyed and the consequences, which is precisely the high-value context this dimension rewards.

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

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

Two sentences with zero waste. The operative purpose is front-loaded in the first sentence, and the second sentence earns its place by adding the critical irreversibility caveat. Every word contributes to the agent's decision-making.

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 one-parameter, no-output-schema, no-annotations tool, the description is nearly complete: it states the action, the target, and the most important behavioral risk. The only meaningful gap is error behavior when the given material name does not exist, which an agent would need to handle failures gracefully.

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 'name' as 'Material name'; the baseline of 3 applies. The description adds only marginal meaning by framing name as the lookup key ('by name'), but provides no extra format, constraint, or edge-case detail beyond what the schema gives.

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 statement, 'Delete a material slot by name,' which precisely identifies the operation and the targeting method. This clearly distinguishes the tool from its material-related siblings (ap_material_create, ap_material_update, ap_material_select, ap_material_list), leaving no ambiguity about what this tool does.

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 usage context is implied rather than explicit: an agent can infer this is the tool to call when a material slot must be removed, and the irreversibility warning implies caution. However, the description never names alternatives or states when-not-to-use conditions, so guidance on choosing it over sibling tools is left to inference.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. The verb 'Report' signals a read-only inspection, and the description names exactly what data is returned. It does not explicitly state that no project state changes, but for a zero-parameter getter this is a minor omission.

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 well-structured sentence leads with the action and resource, then fills in the specific output details and clarifies the terminology ('node-canvas name'). No filler or redundant restatement of the tool name.

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

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

There is no output schema, so the description explains the return payload. It is complete for a zero-parameter getter, though it leaves minor edge-case behavior (e.g., behavior when no material is active) to the runtime.

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

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

The tool has zero parameters, so the baseline is 4; there is no parameter meaning left unexplained. The description correctly avoids inventing parameter details that do not exist.

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

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

The description uses a specific verb ('Report') and resource ('the active material') and precisely enumerates the returned data: the node-canvas name and the nine per-channel paint flags. This distinguishes it from siblings such as ap_material_list, which enumerate materials rather than inspecting the active one.

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

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

The intended use is implied: call this when the agent needs the active material's name or paint flags. However, there is no explicit when-to-use/when-not-to-use guidance or alternative routing (e.g., 'use ap_material_list to see all materials').

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

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

With no annotations provided, the description carries the full burden, and it excels: it explains the snapshot source, when it is null, what it misses, and that no live binding exists. This gives the agent accurate expectations about stale or missing results.

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

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

The description is compact yet information-dense. The purpose is stated first, followed by a clearly labeled caveat, root cause, edge cases, and a sibling alternative—every sentence earns its place without unnecessary filler.

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

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

For a parameterless list tool with no output schema, this description is complete: it explains what is returned, warns about degradation, specifies failure modes, and routes the agent to a more appropriate tool. No critical information for correct invocation or interpretation is missing.

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

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

The tool has zero parameters and the schema already documents this completely, so there is no parameter burden for the description to carry. The description's focus on behavioral caveats is appropriate; a baseline of 4 is warranted for a zero-parameter tool.

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

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

The description opens with a specific verb and resource: 'List material names.' It also distinguishes itself from ap_material_get_active by stating that tool is for the material you are actually working on, so an agent can tell them apart without inspecting 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?

The description explicitly warns when not to trust the tool and points to the correct alternative: 'For the material you are actually working on, use ap_material_get_active.' It also clarifies that there is no live enumeration binding, telling the agent this is not the tool for current-session material discovery.

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

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

With no annotations provided, the description must disclose behavioral details, but it only states the core effect: the material becomes active. It does not mention what happens to the previously active material, error handling for nonexistent names, or whether this affects the current selection context or viewport.

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 concise sentence with no wasted words. The verb, target, and lookup mechanism are all front-loaded and immediately understandable.

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 one-parameter tool with no output schema and no annotations, the purpose and input are adequately conveyed. However, the description omits failure behavior and return semantics, leaving the agent to infer what happens before or after the material is set active.

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

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

The schema already documents the single parameter 'name' with 100% coverage, so the baseline is 3. The description reinforces that the name must refer to an existing material, but it adds no new format, value constraints, or additional parameter context.

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

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

The description states a specific action and object: 'Make an existing material active, by name.' It clearly distinguishes this from material creation, deletion, listing, assignment, and get-active sibling 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 phrase 'existing material' implies the tool is not for creating materials, so usage context is partially conveyed. However, it does not explicitly mention when to prefer this over sibling tools like ap_material_create, ap_material_get_active, or ap_material_assign.

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

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

No annotations are present, so the description carries the behavioral burden. It discloses partial-update semantics and an API limitation, which is helpful. However, it does not state persistence, effects on existing paint data, or what happens if no active material exists.

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

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

Two sentences carry all essential information with no fluff. The action is front-loaded, and the key caveat about omitted channels is included efficiently.

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

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

For a simple optional-boolean setter with 100% schema coverage, the description is nearly complete. It covers scope, partial-update behavior, and a relevant API constraint. Minor omissions like active-material prerequisite and return behavior do not seriously impair usability.

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 are already individually documented. The description adds important semantic value by clarifying that omitted channels are left unchanged and that these flags are the material's own paint_* flags, not texture-set channels.

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?

Description uses a specific verb and object: 'Enable or disable which channels the active material paints into.' It clearly distinguishes these from texture-set channels and notes the plugin API has no channel add/remove, preventing confusion with sibling 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 clear context: it applies to the active material, uses the material's own paint_* flags, and explicitly excludes texture-set channels. It also states that omitted channels are left alone. It does not name alternative sibling tools by name, but the guidance is sufficient for correct 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?

With no annotations, the description carries the full burden and exceeds it: it warns 'THIS DOES NOT CHANGE THE VIEWPORT,' explains the render pipeline (layer stack vs. node graph source), and even provides measured evidence that viewport captures are byte-identical before and after. This is exactly the kind of non-obvious behavior an agent needs.

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 front-loaded with the core purpose and the critical viewport caveat, then gives concise alternatives and a call cadence. Every sentence contributes distinct, actionable information; the measured byte-identical detail is somewhat verbose but directly supports the transparency claim.

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 tool with no output schema and no annotations, the description is complete: it explains what the tool does, when to call it, what it will not do, and how to achieve the visible result the user wants. No critical guidance is missing.

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

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

The input schema has zero parameters and 100% coverage, so there is nothing for the description to add about parameter meaning. The 0-parameter baseline is 4, and the description appropriately focuses on call semantics instead of inventing parameter details.

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

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

The description states a specific verb and resource: 'Recompile the active material after node edits.' It also immediately clarifies that the tool does not change the viewport, which distinguishes it from paint/fill tools and other material operations like ap_material_create or ap_material_delete.

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 explicit when-to-use guidance: 'Call this once after a batch of ap_node_* edits.' It also names alternatives for making edits visible (ap_fill_layer, ap_paint_stroke, ap_paint_stroke_world), so the agent knows exactly how to route its next action.

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

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

No annotations are provided, so the description must disclose behavior on its own. It does state the core mutation (adding a node), the return value, and valid types. It does not disclose side effects, reversibility, or error behavior when no active material exists or an invalid type is supplied.

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 main sentence is compact and front-loaded with the action and return value. The long list of valid types is justified because there is no enum in the schema, and there is no filler or redundant explanation.

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

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

For a tool with three simple parameters, the description covers what it does, where it operates, what it returns, and what input values are allowed. The main gap is not stating the behavior when there is no active material or when the type is invalid, but the core calling context is sufficiently clear.

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

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

The schema already describes x, y, and type, so the description does not need to repeat those. It adds genuine value by listing the full universe of valid node type constants, which is significant because the schema only gives examples and no enum.

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 ('Add'), resource ('node'), target ('active material's graph'), placement ('canvas position'), and return value ('new id'). This clearly distinguishes it from sibling tools like ap_node_remove, ap_node_connect, and ap_node_set_value.

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

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

The description implies usage when a new node should be inserted into the active material graph, and it gives the set of valid node types. However, it does not explicitly say when to prefer this over sibling tools or mention prerequisites such as an active material being present.

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

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

With no annotations, the description carries the full behavioral burden. It adds genuinely useful context — 0-based socket indexing and the exact material socket order — but does not disclose mutation traits such as whether an existing connection is replaced, what happens if either socket is occupied or invalid, or what the operation 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?

Two sentences with zero filler: the first front-loads the core action, the second adds the socket-numbering semantics an agent needs to call correctly. Every sentence earns its place.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description covers the essentials for making the call, but omits behavioral fine points an agent would want: overwrite behavior on occupied sockets, failure modes for invalid node references, and return value. The socket-order detail mitigates but does not fully close the gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by clarifying what socket index values mean: 0-based positions from ap_node_list and the exact material socket ordering (Base Color, Opacity, Occlusion, ...). This goes well beyond the schema's terse 'Source output socket index' and 'Destination input socket index'.

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: 'Link one node's output socket to another node's input socket.' This clearly differentiates it from the sibling tools ap_node_add, ap_node_remove, ap_node_disconnect, and ap_node_set_value, which all perform distinct node-graph operations.

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

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

Usage context is implied rather than explicit: the reference to socket numbers 'as reported by ap_node_list' hints at a precursor step and the 0-based note sets expectations. However, the description never explicitly says when to prefer this tool over ap_node_disconnect or ap_node_set_value, nor gives any exclusion conditions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states that an existing link is removed, which conveys its destructive effect, but it does not mention reversibility, idempotency, behavior on an empty socket, or whether any other connection is affected.

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

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

The description is a single, focused sentence with no filler. The key action and target are front-loaded, making it easy to scan and understand.

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

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

For a simple two-parameter tool with complete schema coverage, the description is minimally viable. However, with no annotations and no output schema, it lacks guidance on side effects, edge cases, and when to prefer it over similar node-related tools.

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

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

Schema coverage is 100%, with both to_id and to_socket already described in the input schema. The description adds little beyond restating that the operation targets one input socket, so it meets the baseline without significantly enriching 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?

The description uses a specific verb ('Remove') and a precise resource ('whatever is linked into one input socket of a node'), clearly distinguishing this from siblings like ap_node_add, ap_node_remove, and ap_node_connect. It communicates the exact operation without ambiguity.

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

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

The description implies the tool should be used when an input socket's existing connection needs to be cleared, but it does not explicitly state when to use it instead of alternatives like ap_node_remove or ap_node_connect. There is no exclusion guidance or contextual routing.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly signals a read-only operation via 'Read', defines the scope as the active material, and describes the full returned contents. It does not mention edge cases such as missing active material or failure behavior, but for a no-parameter read tool the disclosure is solid.

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

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

The description is two sentences with no waste. The first sentence front-loads the precise behavior and output contents; the second adds relevant context about reliability and leverage without unnecessary detail. 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 zero parameters, no annotations, and no output schema, the description is complete: it enumerates exactly what data will be returned and makes the read-only, scoped nature clear. An agent has enough information to call the tool correctly and interpret its results.

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

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

The tool has zero parameters and the schema is empty, so there is no parameter semantics to document. The description appropriately clarifies that the scope is the active material, which is the only implicit input an agent needs to understand. Baseline 4 is appropriate because no parameter docs are needed.

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

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

The description uses a specific verb ('Read') and a specific resource ('the active material's node graph'), then enumerates the exact data returned: node ids, names, types, positions, socket names, and links. This clearly distinguishes it from the sibling mutation tools like ap_node_add, ap_node_connect, and ap_node_remove.

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

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

The description gives clear context for when this tool is useful: when an agent needs the node graph structure to work with nodes, and it emphasizes that node work is where the agent has leverage. It does not explicitly name alternatives or state when not to use it, but for a read-only inspection tool the intended usage is strongly implied.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Remove a node' names the core action, it does not mention whether removal is irreversible, whether connected nodes are also removed, or whether the active material must have a specific state. For a destructive operation, this is a meaningful transparency gap.

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

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

The description is a single concise sentence that front-loads the verb and resource, then adds a useful parenthetical about the id source. There is no redundant or filler content.

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

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

For a one-parameter tool with no output schema, the description gives enough to call it correctly: what action to take, on what target, and where to source the id. The main missing element is a note on side effects, but that was already flagged under behavioral transparency.

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

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

The input schema already documents 'id' as a 'Node id' with 100% coverage. The description adds extra value by specifying that the id must come from ap_node_list, which clarifies where the value originates and helps the agent use a valid identifier.

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 ('Remove'), a clear resource ('a node from the active material's graph'), and the source of the identifier ('from ap_node_list'). This clearly differentiates it from sibling tools like ap_node_add, ap_node_connect, and ap_node_disconnect.

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

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

The description gives useful context—the node should be in the active material's graph and the id should come from ap_node_list. However, it does not explicitly say when to prefer this over alternatives like ap_node_disconnect, nor does it state any exclusions or prerequisites beyond having the id.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains the mutation semantics of each kind, the distinction between socket values and button widgets, and the important follow-up requirement of ap_material_update. It does not cover permissions, errors, or return values, but the core behavior and sequencing are disclosed.

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

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

The description is compact and front-loaded: the first sentence states the purpose, the second defines all variants, and the third gives the critical follow-up instruction. Every sentence earns its place with no filler or repetition.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the main behavioral axes: kind semantics, socket defaults, button specifics, and the required material update. The only notable gap is that button index details are deferred to an external node reference, and there is no mention of return values or error behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real semantic value beyond the schema by explaining what each 'kind' means, how color/vector/float map to socket values, how 'button' maps to widget state, and how the input-socket default works. This lifts it above baseline without fully documenting every 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?

The description opens with a specific verb and resource ('Set a value on a node') and immediately enumerates the four kinds it supports. This clearly differentiates the tool from structural siblings like ap_node_add, ap_node_remove, and ap_node_connect.

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

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

The description gives clear contextual guidance: socket-based kinds default to input sockets, and edits should be followed with ap_material_update. It does not explicitly list when-not-to-use conditions or name alternatives, but the tool's domain is distinct enough that the usage context is clear.

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

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

With no annotations, the description carries the behavioral burden. It discloses the core operation and result, but does not specify behavior for missing names, duplicate name conflicts, or whether children/materials are copied. This leaves some gaps.

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, direct sentence conveys the action, input, and output with no filler. The key information is front-loaded.

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

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

For a single-parameter tool with no output schema and no annotations, the description covers the essential workflow: provide an object name and receive the new duplicate's name. It is adequate for correct invocation, although it omits edge-case behavior.

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

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

Schema coverage is 100% and the description reinforces that the parameter identifies the source object by name. It adds the return-value detail but does not add constraints like uniqueness, existence requirements, or naming conventions for the duplicate.

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

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

The description clearly states the action (duplicate), the resource (scene object), the selection method (by name), and the return value (the new object's name). It is unambiguous and distinct from sibling tools like ap_get_object or ap_object_set_transform.

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

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

The intended use is clear: duplicate a scene object by name. No explicit alternatives or exclusions are mentioned, but the operation is unique among siblings, so the ambiguity is minimal.

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

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

With no annotations at all, the description carries the disclosure burden and does well: it warns that rotation is in degrees, states conversion to quaternion occurs, says omitted components are left alone, and notes the world is Z-up. It doesn't mention whether the operation is destructive or requires any state, but for a transform setter the core behavioral traits are disclosed. The 'rebuild its matrix' note gives useful insight into internal effect.

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

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

Three sentences, no filler. The most important information (what it does, degrees, omitted-left-alone, Z-up) is front-loaded and each sentence earns its place. The structure leads with the verb and resource, then flags the critical unit/conversion detail, then the omission behavior, then the coordinate-space 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 transform setter with 1 required param and 3 optional arrays, the description covers the core usage context. It tells you the coordinate system, the rotation convention, and the omission behavior. It doesn't discuss what the return value is, but there is no output schema and it's not essential for invoking a transform setter. It doesn't mention whether the object must exist, but the parameter description for name plus the tool family context makes that obvious. A half-point deduction for lacking any note about error cases or prerequisites.

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

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

Schema description coverage is 100%, and the parameter descriptions are mostly self-explanatory. The description adds value to rotation_euler_degrees by specifying degrees and conversion, and clarifies semantics of omitted arrays. However, scale and location parameter meanings ('World location', 'Scale') are already in the schema, so the description doesn't add much beyond the schema baseline.

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-object pair ('Set an object's location, rotation and/or scale, then rebuild its matrix'), names the specific resource (an object's transform), and includes a distinctive detail that differentiates from siblings like ap_object_set_visible and ap_get_object: rotation is provided as XYZ Euler degrees and converted internally. It also clarifies omissions are left alone, which disambiguates it from a tool that might reset all components.

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 implicitly tells when to use it: when you need to set transform components of an object, leave unspecified components untouched, and want the matrix rebuilt. It doesn't explicitly state when not to use it or name alternatives, but the sibling set is large and mostly about other concerns (paint, materials, nodes, files), so the context is clear enough. Losing a point because there is no explicit exclusion or alternative pointer.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly states that a hidden object stays in the project with materials intact and merely stops rendering, which goes well beyond the basic show/hide semantics. It does not cover every possible side effect, but for a simple boolean setter it provides meaningful transparency.

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

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

Two concise sentences front-load the core action and then add a valuable clarifying detail about hidden objects persisting with materials intact. Every word earns its place, and there is no redundancy or filler.

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

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

For a simple two-parameter, no-output-schema tool, the description is largely complete: it explains purpose, effect, and non-destructive behavior. It slightly misses out on mention of return values or error behavior, but that is a minor gap given the simplicity of the 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?

The input schema already covers both parameters clearly: 'name' as the object name and 'visible' as 'True to show, false to hide'. Since schema description coverage is 100%, the description does not need to add much, and it does not go beyond what the schema 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?

The description opens with 'Show or hide a scene object', a specific verb and resource, and then clarifies the semantics with 'visible flag' and 'stops rendering'. This clearly positions it as a visibility control tool and distinguishes it from sibling tools that deal with transforms, materials, or scene 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?

No explicit when-to-use or alternative tools are mentioned, but the context is clear: the tool is for controlling whether an object renders. The phrase 'hidden object stays in the project' implies a non-destructive visibility workflow, so usage is reasonably implied even though no direct comparison to siblings is provided.

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

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

With no annotations provided, the description carries the full burden, and it does so richly. It discloses silent no-op conditions (no project, no selected layer, or a group layer), dependence on the selected layer and active tool/brush, the 48-point cap, and the one-frame execution constraint. This goes well beyond a generic 'paint a stroke' statement.

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

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

Every sentence earns its place: the first establishes the core operation, the second explains the coordinate system, the third covers target context and failure behavior, and the final clause adds a hard limit. The density is high but the structure is logical and front-loaded with the most important information.

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

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

The description covers coordinate space, no-op conditions, target layer/tool, the 48-point limit, and the single-frame execution, which is nearly complete for a drawing tool. The only minor gap is that it does not explicitly state the return value or whether the operation reports any result, though 'silently does nothing' implies no error is surfaced.

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

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

The schema already describes points as normalized 0..1, but the description adds meaningful semantics beyond the schema: 0.5,0.5 maps to the viewport center, the stroke is automatically closed, and at most 48 points are allowed—a constraint not present in the schema's top-level array definition. This materially improves correct invocation.

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

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

The description states a specific action ('Paint a stroke in SCREEN space and close it') on a clear resource, and immediately distinguishes this tool from its sibling ap_paint_stroke_world by emphasizing screen-space normalized coordinates and camera dependence. This makes the tool's identity unmistakable.

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

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

The description gives clear context for when this tool applies: when you have normalized screen-space coordinates, and it notes that the painted location depends on the current camera. It does not explicitly name the world-space alternative or say 'use ap_paint_stroke_world for world coordinates,' so it falls just short of an explicit when-not/alternative statement.

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

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

With no annotations, the description carries the full behavioral burden. It discloses several important traits: the stroke is closed, uses world space, is camera-independent, ArmorPaint is Z-up, and ap_get_main_object can provide object bounds. It does not mention prerequisites like an active layer or material, but the core behavioral context 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?

Two sentences carry all the essential information with no filler. The key scoping fact (WORLD space, closed, camera-independent) is front-loaded, and the second sentence adds needed ArmorPaint-specific context about the coordinate system.

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

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

For a single-parameter tool with no output schema, the description is nearly complete: it defines the stroke path space, the closure behavior, the camera-independence rationale, the Z-up convention, and a helper tool for bounds. The main gap is not stating whether an active object/layer/material must already be selected, but this is minor given the simplicity of the tool.

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

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

The schema already covers the points array at 100%, so the baseline is 3. The description adds value by explaining the coordinate system ('ArmorPaint's world is Z-up') and pointing to ap_get_main_object for object bounds, which helps the agent interpret the parameter values correctly.

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 ('Paint a stroke in WORLD space and close it') and immediately distinguishes it from the sibling ap_paint_stroke by emphasizing camera independence. This is enough for an agent to know exactly what this tool does and why it differs.

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 clearly indicates when this tool is preferred: 'reliable choice for scripted painting' because it is camera-independent. It does not explicitly name ap_paint_stroke as the alternative for camera-space strokes, but the world-space contrast makes the usage context clear.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that a real request is sent, what data is returned, and that it validates the end-to-end path. It does not mention failure behavior or side effects, but for a health-check ping this is minor and the core behavior is well described.

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

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

Two tight sentences with no wasted words. The main purpose is front-loaded, the return values are specified, and the comparison to a sibling is included in the second sentence. 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 simple, parameterless ping tool, the description is complete: it says what the tool does, what it returns, and how it differs from the closest sibling. No output schema exists, but the explicitly listed return fields are sufficient for an agent to interpret the result.

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

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

The tool has zero parameters, so there is no parameter documentation burden. The description still adds value by explaining what the no-argument invocation returns, which is more than the empty schema can provide.

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

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

The description opens with a specific verb and resource: 'Round-trip health check' with a clear mechanism ('sends a real request through the file mailbox') and defined return values ('app time, window title and current project path'). It also explicitly distinguishes itself from the sibling ap_bridge_status, making its purpose unmistakable.

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

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

The description explicitly names the alternative ap_bridge_status and draws the comparison: ap_ping confirms the whole path works end to end, while the sibling 'only reads the heartbeat.' This gives an agent a clear decision rule for which tool to invoke when checking connectivity.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose the substance of what the tool returns, but it does not explicitly state that the operation is read-only, non-destructive, or what happens if no project is open. The get_info name partially mitigates this, but the description itself adds limited behavioral detail beyond the field list.

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

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

The description is a single, front-loaded sentence that immediately establishes the scope ('Project-level state') followed by a compact list of returned fields. Every word adds information and there is no filler or redundancy.

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

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

For a zero-parameter getter with no output schema, the description does a good job of explaining what the tool returns by naming the relevant project state fields. It does not mention error conditions or output formatting, but these are minor for such a simple read-only information tool.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There are no parameter descriptions needed, and the description does not omit or obscure any parameter-related meaning.

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

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

The description clearly identifies the tool as returning project-level state and enumerates the specific information included: file path, base path, format version, BGRA flag, environment map settings, and camera FOV. It is distinguishable from sibling tools like ap_get_app_info and ap_get_context by its explicit project scope, though it relies on the tool name for the verb.

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

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

No guidance is provided about when to use this tool versus alternatives such as ap_get_app_info, ap_get_context, or ap_get_config. There are no explicit conditions, preconditions, or exclusion statements, leaving the agent to infer usage from the name and scope.

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

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

The description goes beyond a simple listing by disclosing that the tool operates in a degraded mode, returning a snapshot that may be empty or stale. This is a significant behavioral trait that helps manage expectations, and no annotations were provided to offset this.

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

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

The description is concise, consisting of two sentences that deliver the core purpose and a critical caveat without unnecessary verbosity. It is well-structured and front-loads the primary action.

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

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

Given the tool has no parameters and no output schema, the description provides sufficient context by explaining the tool's purpose and the degraded state of the data. This covers all essential aspects an agent needs to decide when and how to call it.

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

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

The tool has zero parameters, so the schema covers 100% of the input surface. Since there are no parameters, the description cannot add meaning beyond what the schema already conveys, warranting the baseline score of 4.

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

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

The description clearly states the tool's function: listing script assets attached to the project. It is specific about the resource and action, and the additional caveat about degraded mode further clarifies the tool's purpose without ambiguity.

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

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

The description provides an implied usage hint by noting the degraded snapshot behavior, which indirectly tells users when the data may be unreliable. However, it does not explicitly mention alternatives or when to prefer this tool over others, so guidance is only implicit.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool reads live project data rather than a snapshot, and implies a read-only operation. It does not discuss return details, but for a zero-parameter list tool this is adequate.

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

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

Two concise sentences; the main statement is front-loaded and the second sentence adds a valuable distinction without waste.

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, parameterless listing tool, the description covers what it returns ('names of texture assets'), the source ('project_t.assets'), and its live vs snapshot nature. It is complete enough for an agent to select and invoke it correctly.

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

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

The tool has no parameters, so the schema already fully describes input. The description adds no parameter detail, which is unnecessary here; baseline 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?

States a specific verb ('List') and resource ('names of texture assets imported into the project'). The 'unlike material/mesh lists' clause distinguishes it from sibling list 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?

Explicitly marks this tool as the live source ('reads project_t.assets') and contrasts it with material/mesh list snapshots, giving the agent a clear selection criterion. It names the alternative category but not exact sibling tool names.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the destructive consequence: 'Discards the current project WITHOUT prompting and without saving.' This is exactly the kind of critical behavioral trait an agent needs before invoking the tool. It also provides a clear mitigation: call ap_project_save first.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the critical warning follows immediately. Each sentence earns its place; there is no redundant or vague wording.

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

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

For a zero-parameter, no-output-schema tool, the description is fully complete. It explains the action, the destructive side effect, the lack of prompting, and the necessary precaution. An agent has everything required to decide whether and how to invoke the tool safely.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to add regarding parameter meaning. The baseline of 4 applies because no parameter documentation is needed. The description sensibly focuses on behavior rather than parameters.

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

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

The description states a specific verb and resource: 'Start a new, empty project.' It also distinguishes this from related project operations by noting it discards the current project, making it clear this is not ap_project_open or ap_project_save. The purpose is immediately understandable and unambiguous.

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

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

The description gives clear context: use this when starting fresh and abandoning the current project. It also tells the agent to call ap_project_save first if the work matters, which is explicit when-to-use guidance for a destructive action. It does not explicitly contrast with ap_project_open, but the behavior described is sufficient to route an agent correctly.

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

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

With no annotations provided, the description carries the full behavioral burden, and it discloses the most critical trait: "Discards the current project without prompting." This tells the agent the operation is destructive and irreversible with respect to the current session state. It omits permissions, error behavior, and return values, but the single most important runtime consequence is explicit.

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 each earns its place: the action is front-loaded first, then the destructive consequence. No redundant restatement of the tool name or schema content.

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

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

For a single-parameter open command with full schema coverage, the description covers both the action and the critical side effect. Remaining gaps—no return/error behavior and no explicit "save before opening" advisory—are minor and do not mislead an agent about the tool's core behavior.

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

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

Schema description coverage is 100% and the path parameter is already richly documented (absolute path, forward slashes, backslash conversion). The description's ".arm" mention reinforces the file type already present in the schema but adds no new parameter-level semantics beyond it. Baseline 3 applies because the schema carries the weight.

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

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

States a specific verb—"Open"—and resource—"an existing .arm project file." The word "existing" plus the open action clearly distinguishes this from siblings like ap_project_new, ap_project_save, and ap_project_save_as, so an agent can tell it apart without opening any schema.

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

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

Gives no guidance on when to use this tool versus alternatives. It never advises saving the current project first (a natural precondition given the destructive behavior), nor does it name conditions where ap_project_new or other project tools would be preferable. The discard warning implies caution but stops short of actionable usage direction.

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

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

With no annotations, the description carries the full behavioral burden and does so excellently. It discloses the critical deferred-save behavior ('queued' vs 'written'), the specific failure code 'no_project', and the recommended way to confirm the write actually landed.

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

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

Three sentences with no wasted words. The core purpose comes first, followed by the failure condition and alternative, then the critical deferred-save caveat. Each sentence adds necessary information and the most important behavioral warning is prominently capitalized.

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 save operation with no annotations and no output schema, the description covers what an agent needs: the operation, the failure mode, the sibling alternative, the deferred nature, and a verification path. Nothing essential is missing.

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

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

The tool has zero parameters and the schema is trivially fully covered, so there is no parameter documentation burden. The description still adds meaningful semantic context by explaining that 'the current project' and 'its existing path' are the implicit inputs, which is more than the empty schema provides.

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

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

The description states a specific verb ('Save'), a clear resource ('the current project'), and a precise target ('its existing path'). It also distinguishes itself from ap_project_save_as by explicitly naming when that sibling should be used instead.

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

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

It provides explicit when-to-use guidance: use this tool when the project already has a path, and use ap_project_save_as first if it has never been saved. It also recommends ap_fs_stat as a verification step after saving, giving the agent a concrete follow-up action.

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

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

With no annotations, the description carries the burden of behavior disclosure. It clearly explains that the write is DEFERRED to the next frame, that the reply only confirms the path and queued save, and that verification should be done via ap_fs_stat. This meaningfully describes asynchronous side effects beyond the schema.

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

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

The description is two sentences with no filler. It front-loads the core action, then adds the critical deferral behavior and verification pointer in compact form.

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

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

For a single-parameter tool with no output schema, the description gives enough context to call it correctly: what action happens, that it is deferred, what the reply means, and how to verify success. It does not detail error cases or exact return payload, but the provided guidance is sufficient for correct invocation.

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

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

Schema coverage is 100%: the single required path parameter is already documented with format guidance ('.arm file', absolute path, forward slashes, backslash conversion). The description adds nothing further about the parameter, so the baseline score 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 uses a specific verb and resource: 'Set the project file path and save to it,' clearly defining a save-as operation. It distinguishes itself from the sibling ap_project_save by indicating it sets a new path in addition to saving.

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

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

It names the related sibling ap_project_save and contrasts the behavior, implying this tool is for saving to a new/chosen path while ap_project_save likely saves to the current path. It also tells the agent to verify the eventual result with ap_fs_stat, giving practical follow-up guidance, though it stops short of explicit when-to-use versus when-not-to-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?

With no annotations, the description carries the full burden and excels: it discloses the destructive consequence ('Unsaved work is LOST'), provides mitigation ('save first'), and explains the unusual exit behavior (app exits before committing a reply, so 'no reply' is normal). This is exemplary behavioral disclosure.

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

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

Three sentences with zero waste: the action is front-loaded, the critical warning follows immediately, and the reply-behavior caveat closes it. Every sentence earns its place and the structure orders information by importance (action → danger → expected response).

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

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

Despite having no output schema and no annotations, the description covers everything an agent needs: the destructive precondition, the required parameter value, and the expected reply behavior. Nothing is missing for correct invocation of this simple, one-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 coverage is 100% and the schema already documents confirm as 'Must be true. Guards against an accidental shutdown.' The description reinforces 'Requires confirm=true' but adds no new semantic detail beyond what the schema provides, 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?

The description opens with a specific verb+resource, 'Quit ArmorPaint,' which unambiguously states the tool's sole purpose. It is clearly differentiated from all 57 siblings, which cover painting, exporting, filesystem, and project operations — none of which involve terminating the application.

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

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

The description gives clear operational context: save work first, and confirm=true is mandatory. While it doesn't name an alternative tool explicitly, no sibling provides a quitting alternative, and 'save first' implicitly points to the save-family tools. This is clear guidance with no exclusions needed.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the read is local, involves no round trip, works while ArmorPaint is closed, and enforces format and size limits. It does not detail error handling, but covers the key operational traits.

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 focused sentences: purpose first, then workflow, then constraints. No filler; every sentence adds actionable information.

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

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

For a simple read-only tool, the description covers purpose, workflow, format/size limits, and the local/no-round-trip behavior. It lacks explicit error-case handling, but the core information an agent needs to call and interpret the tool is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds global format and size constraints, but no per-parameter detail beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Read an image file from THIS server's filesystem and return it as an image.' It immediately frames the use case as inspecting ArmorPaint exports, which clearly distinguishes it from filesystem listing tools like ap_fs_list.

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

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

Provides clear usage context by pairing with ap_export_textures: 'export, then read one of the reported files.' It also notes the tool works while ArmorPaint is closed. It does not explicitly exclude alternatives, but the intended workflow is evident.

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

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

With no annotations provided, the description carries the behavioral burden. It explicitly discloses that the selection is 'read back from the context' so the result confirms the change took effect, which clarifies the tool's confirmation behavior beyond a bare 'select' command. It does not cover side effects like persistence or permission requirements, but for a simple active-tool setter this is reasonably transparent.

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

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

The description is two sentences with no filler. The first sentence states the action and enumerates the valid values in a list, and the second clarifies the confirmation behavior. Every word earns its place.

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

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

This is a low-complexity tool with one required parameter, no output schema, and no annotations. The description explains what it does, what values are valid, and how the result confirms success. A small gap is not stating any consequences of changing the active tool, but for this simple setter the description is otherwise sufficient.

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

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

Schema coverage is 100%: the only parameter 'tool' has a full enum and a description saying 'Tool name.' The description simply repeats the enum values and does not add deeper semantics about what each tool does, but the tool names are self-explanatory. The baseline of 3 applies because the schema already documents the parameter well.

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

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

The description opens with a specific verb and resource: 'Select the active tool', followed by the complete list of valid tool values. The list and the 'active tool' phrasing make it clear this is about switching the current context tool, which distinguishes it from sibling tools like ap_set_brush or ap_material_select.

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

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

The description implies that this tool is used when the agent needs to change the active tool, but it does not explicitly contrast it with related selectors such as ap_set_brush or ap_material_select. There is no when-to-use or when-not-to-use guidance beyond the obvious 'select the active tool' intent.

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

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

With no annotations, the description carries the behavioral burden and does well by revealing that these are direct context writes, immediate in effect, and that omitted values are preserved. It does not discuss potential failure states or prerequisites, but the disclosed partial-update semantics are valuable.

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-load the action and immediately explain the two most important behavioral nuances: partial updates and immediate application. No filler or repetition of schema details.

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

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

For a simple context setter, the combination of the explicit schema and the description covers what values to provide and how they apply. It could be more complete by noting prerequisites such as requiring an active painting context, but nothing critical about the core behavior is missing.

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

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

The schema already covers all 6 parameters with ranges and units, so the baseline is 3. The description adds meaningful merge semantics beyond the schema by stating that omitted values are left alone, which matters for a tool with zero required parameters.

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

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

The description names a specific verb and resource ('Set brush parameters on the painting context') and is distinct from painting-execution siblings like ap_paint_stroke and ap_paint_stroke_world. It also clarifies the scope of the operation as context configuration, not a stroke operation.

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

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

It gives clear temporal context ('take effect immediately for the next stroke'), which implies it should be called before painting. It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

With no annotations, the description carries the transparency burden. It clearly signals mutation, narrows the writable surface, and discloses the non-obvious layer_res behavior that existing layers are not resized. It does not mention persistence or restart requirements, but it covers the most likely misuse.

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

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

Two sentences with no filler: the purpose is front-loaded, the writable-fields restriction follows, and the layer_res caveat is last. Every clause earns its place.

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

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

The schema documents every parameter, so the description only needs to supply scope and caveats, which it does well. It could add whether changed settings persist or require a restart, but an agent can invoke it correctly with the information given.

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

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

The input schema already describes all 14 parameters at 100% coverage, so the baseline is 3. The description only adds one behavioral clarification about layer_res beyond what the schema states, which is helpful but marginal.

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

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

The description uses a specific verb and resource, 'Change application preferences,' and scopes it to ArmorPaint. This clearly distinguishes it from sibling read tools like ap_get_config.

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?

'Change application preferences' gives a clear when-to-use context. The caveat that only listed fields are writable also sets a hard boundary, though it does not explicitly name alternatives such as ap_get_config for reading values.

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

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

With no annotations provided, the description carries the full disclosure burden. It explicitly says the tool changes the 3D viewport display and clarifies that 'lit' is the normal shaded view while other modes isolate a channel or debug output. This meaningfully describes the tool's behavior, though it does not mention side effects or persistence, which are less critical for a viewport display switch.

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

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

The description is two sentences with no fluff. It front-loads the action and target, exhaustively lists accepted values, and then provides the key clarification about 'lit' versus the other modes. Every word earns its place.

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

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

For a single-parameter setter with an exhaustive enum and no output schema, this description is complete. It tells the agent what the tool changes, what values are accepted, and what those values mean in context, so the agent can call it correctly without additional information.

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

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

The schema already documents every enum value with 100% coverage, so the baseline is 3. The description adds value by explaining that 'lit' is the normal shaded view and all other modes isolate a channel or debug output, giving the agent semantic understanding beyond the raw enum list.

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 ('Set') and identifies the exact resource ('what the 3D viewport displays') before enumerating all valid modes. This clearly distinguishes it from sibling tools like ap_capture_viewport or ap_set_config, which have different purposes.

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

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

The description implies when to use the tool—whenever you need to change the viewport display channel—and explains the semantics of 'lit' versus other modes. However, it does not explicitly state when not to use it or name alternative tools for similar tasks, so the guidance is 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?

No annotations are present, so the description must carry safety and side-effect disclosure. It does disclose a concrete side effect: 'direct writes to project_t', indicating immediate mutation of project state. However, it does not comment on reversibility, whether the project must be saved, or whether this affects rendering or undo. This is partial transparency.

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

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

A single sentence, front-loaded with the action and listing both parameters. The parenthetical side-effect note is useful and does not bloat the definition.

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

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

For a two-optional-parameter setter, the description plus schema cover the what and the parameters. However, with no annotations and no output schema, it omits whether a project must be open, what the operation returns, and whether writes require a save to persist. The cryptic 'project_t' reference also assumes internal knowledge.

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

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

Schema coverage is 100%, and the schema already describes angle as radians and strength as a multiplier with a minimum. The description adds no parameter details beyond restating the two properties in prose. 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 uses a specific verb ('Set') and resource ('environment map'), and explicitly names the two mutable aspects (strength, rotation angle). It reads distinctly from siblings like ap_import_envmap and ap_set_config, so an agent can distinguish it 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?

The description states the operation directly, so an agent can infer when to use it. However, it does not mention any alternatives or exclusions, nor prerequisites like an open project or an imported envmap. With no explicit when-to-use guidance, it relies on the tool name and sibling 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?

With no annotations, the description carries the full behavioral burden. It makes the action's additive nature clear, lists special values like 'empty', and warns that exact names are build-specific. It does not mention return values or preconditions like an open project, but for a simple create-primitive operation that is a minor gap.

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

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

Two sentences with no wasted words. The action and object are front-loaded, and the alternative lookup instruction is placed efficiently at the end.

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

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

The tool is simple: one required parameter, no output schema, and no nested objects. The description plus schema are nearly sufficient for correct invocation. A small gap is the absence of any statement about return values or error behavior if an invalid name is passed.

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

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

The schema already covers the single parameter with 100% coverage, so the baseline is 3. The description adds value by emphasizing that names are build-specific and by pointing to ap_shape_list for authoritative values, which helps the agent supply a valid parameter.

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

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

The description uses a specific verb ('Add'), a clear resource ('a built-in primitive'), and scopes the action to 'the scene'. It lists the available shapes and distinguishes itself from ap_shape_list by clarifying it creates rather than lists.

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

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

It gives a clear, actionable alternative: use ap_shape_list for this build's exact names. This is strong contextual guidance for choosing whether to call this tool or its sibling, though it does not enumerate exclusions for other potentially related tools like ap_append_mesh.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states results come 'from the running build,' signaling the list is dynamic, and the word 'Typically' warns the enumerated values are not guaranteed to be exhaustive. It stops short of describing the exact return format, but for a parameterless list tool this is sufficient.

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

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

Two sentences with no wasted words. The first sentence states the verb and resource, and the second provides concrete typical values. The structure is front-loaded and every sentence contributes useful information.

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

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

Given zero parameters and no output schema, this description is complete for practical use. It communicates the return concept (a list of built-in primitive shapes), the source (the running build), and representative examples. An agent can call this tool correctly and interpret the result without further clarification.

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

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

The tool has zero parameters, so the baseline for this dimension is 4. There is no parameter documentation needed, and the description focuses instead on the output and relationship to ap_shape_add.

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 action and resource: 'List the built-in primitive shapes that ap_shape_add accepts.' This clearly ties it to the sibling ap_shape_add tool and distinguishes it from other list tools like ap_fs_list or ap_node_list. The scope is unambiguous.

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

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

The description makes the usage context obvious: use this tool to discover valid shape names to pass to ap_shape_add. It does not name alternatives or exclusions, but no sibling tool offers this capability, so the intended context is clear enough.

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

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

With no annotations, the description carries the disclosure burden. It goes beyond the schema by revealing that the toast is transient, the modal blocks ArmorPaint's UI thread, and the bridge stalls until dismissal. This is meaningful behavioral context beyond the parameter defaults.

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

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

Two sentences, front-loaded with the core function and immediately followed by the important caveat and recommendation. Every sentence earns its place without redundancy.

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

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

For a simple message-display tool, the description plus the fully covered schema provide enough to call it correctly. The key risk, modal-induced bridge stalling, is disclosed. No output schema exists, so not detailing return values is acceptable.

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 four parameters. The description adds context about toast vs. modal behavior but does not enrich individual parameter meaning beyond what the schema already provides, 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 and resource: showing a message to the user in ArmorPaint, with toast or modal variants. It is clearly distinct from the many painting/importing tools, though it does not explicitly differentiate itself from the closely related ap_console_write 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?

The description explicitly advises preferring the toast and warns that a modal blocks the UI thread and stalls the bridge until dismissed. This gives clear when-to-use guidance for the modal option, but it does not address when to choose this tool over ap_console_write for message-like output.

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