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

Annotations already declare readOnlyHint, idempotentHint, and closed-world scope, so safety is covered. The description adds genuine value beyond that by describing the return artifact (changed-pixel mask over the texture map) and the magenta encoding for changed regions.

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

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

Three compact sentences, front-loaded with the core action and ending with the return convention. Nothing is wasted, though the return-value sentence partially overlaps with the existing output 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?

With a full output schema, rich annotations, and fully documented parameters, the description only needs to frame intent and it does so. A brief note on what inputs are accepted (JSON object vs. text) would close the small remaining gap.

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

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

Schema description coverage is 100% and both before/after parameters are fully documented in the schema, including the skinspec.v1 format reference. The description adds no additional parameter-level guidance, so the baseline 3 applies.

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

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

States a specific verb (compare/diff) and resource (two skin specs) plus the output granularity (per-face, pixel by pixel). This clearly distinguishes it from write-oriented siblings like texel_patch or rendering siblings like texel_render.

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?

"Use it to confirm a patch touched only what you intended" gives a concrete scenario, implicitly positioning it after texel_patch. It does not, however, name an alternative tool or state any when-not-to-use condition.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description adds only 'complete, working example' (i.e., the output is usable as-is), and says nothing about size, whether the spec is renderable, or its relationship to the live state. Modest value-add over the annotations.

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

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

Purpose is front-loaded in the first sentence, followed by the required enumerations. The long id list is justified given 0% schema coverage, though grouping labels ('Skins', 'Family') are slightly cryptic without 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?

One required parameter fully enumerated, no output schema needed since the description says it returns a spec, and annotations cover the read-only/idempotent nature. Remaining uncertainty (spec format, size, downstream use) is minor for a simple read tool.

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

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

Schema description coverage is 0%, so the description carries the burden and does so by enumerating all 14 accepted ids and grouping them ('Skins:' vs 'Family:'), which matches the single enum parameter exactly. It does not explain id semantics beyond the naming, but the enumeration compensates well for the empty schema.

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

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

States a specific verb and resource ('Return a complete, working example spec') and clarifies its intent with 'to learn from or fork'. It does not name any sibling, but the resource is distinctive enough that an agent can separate it from texel_read_docs or texel_pull.

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?

'to learn from or fork' implies the use case (reference material, starting point for authoring), which is useful context. However, it never states when to prefer this over siblings like texel_pull or texel_read_docs, nor what to do with the result (e.g., feed it to texel_save or texel_patch).

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

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

Annotations establish read-only, idempotent, non-open-world behavior. The description adds useful behavioral detail beyond that: conversion produces one layer per painted face and palette keys c01…cNN, with player-skin defaults and layout-specific outputs. It stops short of covering error or permission behavior, but the annotations carry the safety profile.

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 conversion action, then covers default behavior, layout overrides, and a brief post-import note. Every sentence contributes to correct invocation or expected output understanding.

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

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

With annotations covering safety and an output schema covering return values, the description needs only to explain the operation, default layout, and output structure. It does all three, including the editable-spec format and palette-key convention, leaving no critical gaps for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents path and layout. The description still adds value by clarifying the default player-skin dimensions (64×64 or legacy 64×32) and expanding the layout options beyond the schema's examples to mob, armor, cape, item, and block textures.

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: "Convert an existing PNG in the workspace into an editable spec." It also clarifies the default player-skin scope and the layout override, so an agent can tell this apart from siblings like texel_render or texel_save.

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

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

It implies when to use the tool via "Convert an existing PNG ... into an editable spec" and explains the layout parameter's role. However, it does not explicitly compare the tool with alternatives such as texel_patch or texel_render, so usage guidance remains inferred rather than direct.

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

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

Annotations already declare the safety profile (non-readonly, idempotent, non-destructive), so the description's value is in the mechanics it adds: the session can be reused, and every texel_render output streams into the open browser tab. That live-relationship context is not derivable from structured fields. It doesn't cover session lifetime/teardown, hence not a 5.

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

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

Front-loaded with the verb and the returned artifact, then rationale, then the call instruction. Three sentences carry their weight, though 'so they can watch the skin evolve and give feedback mid-way' is mildly verbose.

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-param tool with an output schema and annotations, the description covers purpose, when to call, and the key live-render behavior. Return-value details are rightly left to the output schema, leaving little missing.

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

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

Schema description coverage is 100%, so the open and port parameters are fully documented in the schema. The description adds no parameter detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Start (or reuse) a live session and return a studio URL'), and the live-preview purpose is distinct from the batch siblings like texel_render. An agent can tell what this tool does 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?

Gives clear timing guidance ('Call it before the first render and share the URL with the user'), which is the key usage decision. It does not state when not to use it or name a competing sibling explicitly, so it stops short of a full 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds real context beyond them: colors are returned most-common-first, each tagged with a role, and delivered as "palette" and "legend" keys. It doesn't discuss failure modes for non-PNG or missing paths, but for a read-only tool this is solid 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?

Two dense sentences that front-load the core action and then the usage hint; every clause earns its place. The nested quotes around "palette"/"legend"/"~" add a little visual clutter but no real padding.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still conveys the ordering and role semantics that matter for downstream use. Combined with annotations covering safety, an agent has what it needs to call and interpret the tool correctly.

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

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

Schema description coverage is 100% and both parameters (path, colors) are fully documented in the schema, so baseline 3 applies. The description never mentions the colors-count parameter or its bounds, adding no meaning 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 gives a precise verb+resource ("Read a reference PNG ... and return its main colors") plus the exact output shape (a spec "palette" and "legend"). It implicitly separates itself from texel_import_png by clarifying the return is a palette with role-annotated colors, though it never names a sibling explicitly.

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

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

It states a clear use case ("Use it to match a reference instead of guessing hex values") and a follow-up workflow ("derive the other tones with '~' steps"). It does not name the alternative tools an agent might pick instead, so it stops short of full when/when-not routing.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds real behavior beyond them: auto-assigned persistent ids ('<op>-<index>'), graceful skipping with reporting of non-applicable entries, and an in-place file write in 'file' mode. The non-idempotent hint is effectively explained by the retained id assignment. It stops short of covering permissions or error/failure rollback semantics.

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 lead sentence front-loads the core action and its scope, and the remaining sentences each carry distinct information (id persistence, skip-and-report, mode-specific returns). It is dense with parenthetical detail but every clause earns its place, with 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 mutating tool with full annotation coverage and an output schema, the description supplies the operation set, the id-lifecycle rule, failure handling, and mode-dependent output differences. The main omission is guidance on invalid patches beyond 'skipped and reported' and any permission or workspace 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by contrasting 'spec' versus 'file' outcomes (patched spec + review + sheet vs. write-back + review + sheet) and by explaining that ids assigned to anonymous layers persist for reuse. This is genuine semantic value layered over an already-complete schema.

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

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

States a specific verb and resource ('Apply a patch to a spec'), enumerates the operations it supports (update, replace, add or remove layers; change palette, legend or meta), and explicitly relates itself to a sibling ('render the result like texel_render'). An agent can distinguish this from texel_render and the other siblings 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?

Describes the two operating modes ('spec' vs 'file') and their distinct return behaviors, and implies the patch-then-render workflow relative to texel_render. It does not, however, state explicit when-not conditions or route the agent to alternatives such as texel_validate or texel_diff for non-mutating checks.

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

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

Annotations already establish safety (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description adds real context beyond that: the accepted link forms (full URL, bare id, studio link with #z= / #spec=) and the fact that the call is non-mutating loading of an existing spec.

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 action and followed by accepted-input detail and the return type. No filler or restated title text.

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?

An output schema exists, so return-value detail is unnecessary, and annotations cover the safety profile. For a single-parameter read tool, everything needed to call it correctly is present.

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

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

Schema coverage is 100% and the single parameter is documented as 'A share link or short id', establishing a baseline of 3. The description goes beyond that by enumerating the studio-link fragment forms (#z= / #spec=), which the schema does not mention.

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

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

The description gives a specific verb (Load) and resource (the spec behind a Texel share link) plus the motivation (keep developing an existing skin) and the return (spec JSON). It does not name any sibling, so an agent must infer that texel_get_example or texel_import_png are not the right choices, which keeps it short of a 5.

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

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

The clause 'so you can keep developing an existing skin' implies the use context but never states when to prefer this over texel_get_example, texel_share, or texel_import_png, and gives no exclusions or prerequisites. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered by structured data. The description adds the return-format disclosure ('as markdown'), which is real behavioral context the annotations don't provide, though nothing is said about pagination or response size.

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

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

Front-loaded verb and format, then a compact enumeration of valid pages, then the one actionable tip. Every clause earns its place with 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 one-parameter read-only tool with no output schema, the description supplies everything needed: what it returns (markdown), the full valid page set, and guidance on which page to read first. Nothing required for correct invocation is missing.

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

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

Schema description coverage is 0% and the single parameter is an enum, so the description must carry the meaning — and it does, glossing all six values (protocol, spec, art-guide, families, api, install). Some glosses are near-tautological ('spec (Skin spec reference)'), keeping it short of a 5.

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

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

States a specific verb ('Read') and resource ('a documentation page') plus the return format ('as markdown'), which no sibling like texel_validate or texel_render shares. An agent can distinguish this from the other texel_* tools 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?

Gives concrete usage context by enumerating which topic each page covers and adds a sequencing directive ('Read "spec" before writing your first spec'). It does not name when NOT to use it or an alternative tool, but for a docs reader the 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the bar is lower; the description nonetheless adds that the operation is deterministic and never modifies files, which is a stronger guarantee than the hints alone. The output enumeration adds context even though the output schema carries the detail.

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 core purpose is front-loaded in the first clause, and the remaining sentences carry real content. The parenthetical enumerations are dense and slightly run-on, but no sentence is pure 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?

With annotations covering the safety profile and an output schema covering return values, the description supplies the missing glue: what is compiled, what the review contains, and what optional outputs exist. It stops short of stating prerequisites or relationships to the sibling validation/patch 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%, so file/spec/focus/include are already documented in the schema; the description's "on request" phrasing loosely tracks the include flag but adds no format or syntax detail beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ("Compile a skin spec and review it") and enumerates exactly what the tool produces, which cleanly separates it from siblings like texel_validate, texel_patch, or texel_save. An agent can tell what this tool does 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?

Usage is implied (render/review a skin spec) and the optional-output switch is signalled with "on request," but no when-to-use versus when-not guidance is given, and no alternative such as texel_validate or texel_render_family is named. Nothing misleading, just no explicit routing.

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

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

Annotations already declare readOnly, idempotent, closed-world, so safety is covered. The description adds genuine behavioral context: it discloses that all members are expanded and reviewed and that the output is a lineup image with front and back of each member in order plus a score table. It does not mention cost, size limits, or failure modes for invalid families.

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, no filler, front-loaded with the action and followed by the concrete output. 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?

With an output schema present, return values need not be explained, yet the description still sketches them. The main gap is sibling routing and any prerequisite about valid family specs, but overall the definition is complete enough 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% and the schema documents the single family parameter with a doc reference. The description still adds meaning by unpacking the family shape ('base spec + variants and/or a matrix of axes'), clarifying what kinds of input the object may contain beyond the schema's terse format pointer.

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 (expand/review) and resource (a skin family of base spec + variants/matrix), and describes the deliverable (lineup image plus per-member score table). It is clearly distinct from texel_render (single render) and texel_save_family (persistence), though it never names those siblings explicitly.

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

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

Usage is implied by 'expand a family ... and review every member', which tells the agent this is for batch/family review rather than a single render. However, there is no explicit when-to-use/when-not or routing to texel_render, texel_save_family, or texel_validate.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds significant behavioral detail: it writes multiple concrete files into the workspace at specific relative paths, and it refuses specs that contain errors. This goes beyond what the annotations convey.

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

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

One dense sentence front-loads the core action (compile and write) and enumerates artifacts compactly. Every clause carries information; nothing is repeated or wasted.

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

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

Covers the three output files, the optional review sheet, and the error-refusal condition, and an output schema exists so return values need not be explained. It lacks guidance on when to call texel_validate first or how this relates to texel_save_family, leaving a small gap.

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

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

Schema description coverage is 100%, so the schema already documents each parameter fully. The description reiterates the meaning of 'sheet' ('optionally <path>.sheet.png') and extends the <path> parameter into the actual filenames written, which is some value, but does not add format or syntax details beyond the schema. Baseline 3 is appropriate.

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

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

States specific verb (Compile and write) and enumerates exactly which artifacts are produced: <path>.png, <path>.skin.json, and optionally <path>.sheet.png. The 'Refuses specs with errors' clause further sharpens the purpose against siblings like texel_validate.

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 spec must be valid ('Refuses specs with errors') and that sheet controls the optional output. However, it does not name alternatives like texel_validate (to check a spec before saving) or texel_render, nor state when to prefer this over texel_save_family. Usage is inferred rather than explicit.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely new context: the exact files written, that output lands in the /app workspace, and that malformed families are rejected. It does not contradict any annotation. It stops short of stating permissions or overwrite semantics, keeping 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?

Two tightly packed sentences with zero filler, front-loaded with the core action and file outputs before the failure-behavior note. 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?

An output schema exists, so return-value documentation is unnecessary, and the description covers the created files and workspace location adequately. What remains missing is guidance for choosing this tool over texel_save/texel_render_family, but the operational picture is otherwise 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 both parameters (family format reference, directory example). The description reuses the <directory> placeholder but adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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

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

The description gives a concrete verb ("Expand a family and write") and enumerates the exact artifacts produced (<member-id>.png, .skin.json, lineup.png). This clearly distinguishes it from the single-file sibling texel_save. However, it never disambiguates against the potentially overlapping texel_render_family sibling, which an agent could easily confuse with this save tool.

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

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

The note "Refuses families with errors" hints that input should be validated first (texel_validate), but no explicit when-to-use or when-not-to-use guidance is offered. With 13 siblings including texel_render_family and texel_save, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and idempotentHint=true, so the safety profile is partly covered, yet the description still adds real value: it discloses a remote store, the exact short-link format returned, and a degradation path (long self-contained link) when offline. One tension remains — 'Store the spec on <host>' describes a remote write while readOnlyHint=true suggests no side effect — but since the write is external and openWorldHint=true explicitly signals outside interaction, the description does not actively deceive the agent.

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, zero filler, and the primary behavior (store + return short link) is front-loaded ahead of the fallback clause. Every phrase carries information an agent needs.

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

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

With an output schema present, return details need not be spelled out, and the description still notes the link format and offline fallback. Annotations cover safety. The remaining minor gap is that it says nothing about what happens on a non-offline failure (invalid spec, server error) or whether produced links are permanent.

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?

There is a single required parameter with 100% schema description coverage, and the schema already points at texel://docs/spec and texel://schema/skinspec.v1 for the format. The description only restates the parameter ('the spec') and adds no format, size, or validity constraints beyond what the schema supplies, so the baseline 3 applies.

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

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

The description gives a specific verb plus outcome: it stores the spec remotely and returns a short link that opens the exact skin in the studio, including the URL shape (/s/<id>). That is much more concrete than 'share a skin'. It does not, however, explicitly contrast itself with likely-confusable siblings such as texel_save or texel_live, so an agent must infer the distinction.

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

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

Usage is only implied by the word 'share' in the title and by the link-producing behavior; there is no explicit 'use this when' statement, no exclusion ('do not use to persist locally — use texel_save'), and no prerequisites such as network/auth needs. The offline fallback is a runtime condition, not selection guidance.

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

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

The annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered; the description adds two things they don't: no image rendering (no output artifacts) and low cost, which matters for an agent deciding to call this after every edit. It says nothing about error/warning severity or exit behavior, but the output schema covers the return shape.

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 clauses, zero waste; the purpose lands first and the cost/usage hint second. Nothing here is a restatement of the name or title.

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?

An output schema exists, so return values need no explanation, and the schema fully documents both optional inputs. With annotations carrying the safety profile and the description carrying purpose plus call frequency, an agent has everything needed to invoke this 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?

Both parameters are optional with 100% schema description coverage, and the schema itself explains the file-vs-spec tradeoff and the texel_patch handoff far better than the description could. The description contributes nothing parameter-specific, so the baseline 3 applies.

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

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

Specific verb and resource: "Check a spec for errors and warnings," with a scoping qualifier ("without rendering images") that implicitly separates it from texel_render. It stops short of naming a sibling, so an agent still has to infer that texel_render is the rendering alternative.

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?

"Use it after every edit" gives an explicit trigger for calling the tool, which is real usage guidance rather than silence. It offers no when-not-to-use condition and never names texel_diff or texel_render as the alternatives at the other end of the workflow.

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