ap_export_textures

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.