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

With no annotations, the description carries the full behavioral burden. It usefully discloses what is cleared and the hardware scope, but it does not describe whether the clear is reversible, what response is returned, or any auth/error behavior. This is adequate but leaves meaningful behavioral 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?

Three short sentences front-load the action and then cover hardware scope and target setup. There is no redundant or filler text, 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?

For a zero-required-parameter tool with a richly documented nested target schema and no output schema, the description covers purpose, hardware constraints, and target resolution. It is only missing explicit return/error behavior, which is a minor gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so the nested target fields are already documented. The description adds minor guidance by pointing at target.hardware for direct LAN use and device discovery, but most parameter semantics remain in the schema, making baseline 3 appropriate.

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

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

The description gives a specific verb ('Clear'), an explicit resource ('all HTTP text and display-list overlays'), and the underlying command ('Draw/ClearHttpText'). It also scopes the operation to particular PIXOO64 hardware profiles, so an agent can immediately distinguish it from text-sending siblings like pixoo64_send_text.

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 hardware restriction ('PIXOO64 Hardware 90/92/96 only') acts as a clear when-not condition, and the description tells the agent how to supply or resolve the target. It does not explicitly name alternative tools such as timegate_clear_text or describe sibling selection, but the operational 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 full burden and does it well: validation happens before sending, execution stops on first failure, earlier commands may already have run (partial-failure risk disclosed), and nested/unsupported commands are rejected. The firmware-dependent dispatch difference between 90/92 and 96 is also surfaced.

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?

Dense but front-loaded: validation-first, then hardware behavior, then failure semantics, then scope. The firmware-version detail ('firmware 90102+') is slightly more than an agent needs to call it correctly, but nothing is redundant.

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

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

No output schema and no annotations, so the description must cover behavior, which it largely does — hardware gating, failure mode, rejection rules, and target resolution. The remaining gap is what the call returns (per-command results, validation-only vs executed) and whether validation is a dry run, which the ambiguous opener 'Validate all commands before sending' leaves open.

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

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

Schema coverage is only 50%, and the description compensates by constraining the commands array (nested lists and unsupported commands rejected, hardware gate) and telling the agent to supply target.hardware for direct LAN rather than rely on discovery. It does not clarify limits such as the 40-command cap or ordering semantics, leaving some schema gaps unfilled.

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 makes clear this tool takes a list of commands, validates them, and dispatches them to a PIXOO64 device, with hardware-dependent dispatch behavior. It is distinguishable from the single-purpose siblings (send_text, set_brightness) as a batch path, though it never states plainly that the batch is executed in order on the device.

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 setup guidance ('Provide target.hardware for direct LAN use, or resolve it using device discovery') and a device scope (Hardware 90/92/96 only), so usage is implied. But it never says when to prefer this over pixoo64_send_items or pixoo64_raw_command, and gives no explicit exclusion for those 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 full burden of behavioral disclosure. It usefully clarifies that explicit Hardware is a caller override rather than a device query and that only PIXOO64 Hardware 90/92/96 is supported, but it does not explicitly state that this is a read-only operation, nor does it describe failure behavior or return-shape details.

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 three focused sentences and front-loads the tool's purpose before covering hardware override and target selection. It is compact overall, though the phrase about 'version-specific route and declared MCP support' is somewhat opaque.

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 does identify the high-level information returned and explains target.hardware handling. However, it leaves out important context such as the expected return structure, error behavior when discovery fails, and explicit read-only safety, which matters given the lack of structured metadata.

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 nested target fields are already well documented in the input schema. The description adds some nuance by emphasizing that target.hardware is an override and should be used for direct LAN access or resolved through discovery, but most parameter meaning remains supplied by 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 states a specific verb, 'Report', and specific resources: the 64x64 profile, version-specific route, and declared MCP support. It also scopes the tool to PIXOO64 Hardware 90/92/96, which helps distinguish it from the TimeGate and watchface device-info siblings, though it does not explicitly name those alternatives.

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

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

It gives some usage context, such as providing target.hardware for direct LAN use or resolving it via device discovery, but it does not explain when to use this tool instead of timegate_get_device_info or watchface_get_device_info. The intended usage is implied by the tool name rather than fully specified.

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 must carry the behavioral burden; it does disclose the value mapping (1=on, 0=off) and the hardware prerequisite, and the target fallback to environment variables comes from the schema. It says nothing about failure behavior, idempotency, or what a successful response looks like, which matters for a device-control call.

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

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

Three short sentences with the most decision-relevant information (value mapping, hardware restriction, routing method) front-loaded. No filler; only the protocol-label phrasing adds slight noise.

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 binary toggle the description covers the essentials, and there is no output schema to explain. However, with no annotations and no return-value guidance, an agent cannot tell whether success is signalled by a result payload or an error, leaving a modest completeness 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 50%, and the description compensates for the key gap by explaining the undocumented required parameter onOff (1=on, 0=off), which the schema gives no description for. The nested target properties are already documented in the schema, so no further detail is needed there.

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 operation (set OnOffScreen to on/off) and scopes it to PIXOO64 hardware 90/92/96, which implicitly separates it from the timegate_onoff_screen and watchface_onoff_screen siblings. The phrase 'Set Channel/OnOffScreen' mixes protocol jargon with the operation, but the intent is still readable.

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 tells the agent the applicable context (PIXOO64 90/92/96 only) and how to route the call (target.hardware for direct LAN, or device discovery). It never explicitly names timegate_onoff_screen as the alternative for TimeGate devices, leaving the routing to inference from the hardware restriction.

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 load and does so well: it discloses that the device itself downloads the URL (so a URL must be device-reachable, not just client-reachable), the accepted dimensions, hardware gating, and that target falls back to environment variables when omitted. It does not describe whether the call blocks until playback finishes or how failures surface, 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?

Four tight sentences with no filler, front-loaded with the action and immediately followed by constraints. The staccato style ('Legacy firmware requires 90096+. PIXOO64 Hardware 90/92/96 only.') is dense but each clause adds a distinct constraint rather than restating another.

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

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

No output schema and no annotations, so the description must be self-sufficient about constraints, and it is: sizes, firmware, hardware models, target resolution, and the device-side download model are all present. Remaining gaps — timeout behavior, error semantics, and what state the display is left in — are secondary for this tool but not trivial.

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 only 50%, and the undocumented parameter is the required 'url' — the description compensates by stressing 'device-accessible HTTP GIF URL', which tells the agent the URL must be fetchable from the device rather than from the caller, plus the 16/32/64 size constraint. The hardware/discovery guidance also disambiguates target usage beyond the schema text.

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 ('Play a device-accessible HTTP GIF URL using Device/PlayTFGif') plus the supported sizes, so the agent knows exactly what will happen. The pixoo64 prefix and the 'PIXOO64 Hardware 90/92/96 only' clause separate it from timegate_play_gif and from pixoo64_send_animation, though no sibling is named outright.

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

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

Gives concrete eligibility conditions (legacy firmware 90096+, PIXOO64 Hardware 90/92/96) and a routing instruction for target resolution: set target.hardware for direct LAN or use device discovery. It stops short of saying when to prefer this over pixoo64_send_animation or timegate_play_gif, so no explicit exclusion is offered.

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 full load and does so well: it discloses mutation of device state ("reset the HTTP GIF ID then use PicID=1"), partial-failure semantics ("Stops on first failure; never retries a partially sent animation"), and hardware gating. It does not state what is returned on success, what error shape a mid-sequence failure yields, or any timeout/rate considerations for a tool that writes 59 frames.

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 payload shape and limits, then failure semantics, then model gating, then target resolution — a sensible order with no filler. The "reset the HTTP GIF ID then use PicID=1" clause is protocol jargon that is dense but earns its place by explaining a required pre-step.

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 4 parameters, a nested target object, no annotations, and no output schema, the definition covers the risky parts (format, limits, partial failure, hardware) but leaves gaps an agent would want: no statement of the return value or error format, and no linkage between frame encoding and the width parameter. Adequate but not fully self-sufficient for a state-mutating device write.

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

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

Schema description coverage is only 25%, so the description must compensate — and it does for the most important param, explaining that frames are ordered row-major RGB base64 subject to the 1–59 limit. However, width (16/32/64), speed (1–65535), and timeoutMs get no semantic explanation anywhere, and the row-major format only makes sense in relation to width, which is never connected.

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

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

States a specific verb+resource (Send ... frames) with the cardinality constraint (1–59) and the wire format (row-major RGB base64, not PNG/JPEG/GIF bytes). The format clause also implicitly separates it from the sibling pixoo64_play_gif, which takes GIF bytes, so an agent can route without opening either 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 a hard model exclusion ("PIXOO64 Hardware 90/92/96 only"), which is a clear when-not, plus concrete direction on how to select the target ("Provide target.hardware for direct LAN use, or resolve it using device discovery"). It stops short of naming pixoo64_play_gif as the alternative for GIF input, so the sibling choice is left slightly 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?

No annotations are provided, so the description has to carry the whole behavioral load, and it does disclose key traits: the animation prerequisite, overwrite semantics ('IDs 0–39 replace matching overlays'), hardware gating, and the optional background initialization. It still doesn't say what the call returns, what happens if no animation exists, or whether items persist after the call.

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

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

The description is tightly written, front-loads the action, and each sentence carries a distinct constraint (prerequisite, ID replacement, guide pointer, hardware, target resolution). It is dense and skips connective tissue, but no sentence is 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 no annotations, no output schema, and nested parameters that the schema covers only partially, the description supplies the behavioral and configuration context an agent needs: the animation prerequisite, overlay-ID semantics, hardware restriction, and target resolution. It stops short of describing the response or device-side failure modes.

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

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

Schema description coverage is only 33%, so the description has to compensate, and it does. It explains the item-array model (IDs 0–39 replace overlays, types 1–23 per the guide, font policy), the side effect of backgroundColor (starts a solid 64×64 background before drawing), and the role of target.hardware as an explicit profile or a discovery-resolved value.

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?

It states a concrete verb and resource ('Send time/date/weather/text elements'), names the underlying protocol call (Draw/SendHttpItemList), and sets the scope (64×64 overlays). It is distinguishable from pixoo64_send_text because it works through the item list rather than a simple text send, but it never names the sibling to draw that contrast 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 gives real preconditions: it requires a previously sent animation, backgroundColor is optional for a solid backdrop, it works only on Hardware 90/92/96, and target.hardware must be supplied or resolved through discovery. It lacks an explicit rule for when to choose this tool over pixoo64_send_text or timegate_send_items, so the guidance is clear but not complete.

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 carries the load, and it discloses key behavior: it mutates/replaces an existing overlay, requires a prior animation to exist, and backgroundColor triggers a solid 64×64 background first. It omits what happens to other existing overlays and the response shape, but the state dependencies and side effects are well covered for a mutation 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?

Four compact sentences, front-loaded with the core action, followed by prerequisites and device constraints. Each clause carries useful information with little padding, though the device/firmware constraints are densely stacked without clear grouping.

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

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

For a complex nested-parameter mutation tool with no annotations and no output schema, the description covers hardware and state requirements well but leaves the meaning of several text sub-fields and the return behavior unaddressed. An agent can call it but may misconfigure TextId or dimensions.

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 only 33%, and many nested text fields (TextId max 19, x/y, TextWidth, color, align, dir, speed) are undocumented anywhere. The description clarifies backgroundColor's effect and target.hardware's meaning, but the font range 0–7 merely restates the schema's min/max and TextId replacement semantics are only hinted at.

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?

"Add or replace a text overlay using Draw/SendHttpText" states a specific verb and resource and names the underlying command. It distinguishes itself from related siblings like pixoo64_clear_text and timegate_send_text by the PIXOO64 hardware constraint, though it doesn't explicitly route away from them.

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

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

Gives concrete prerequisites: requires a previously sent animation, legacy firmware needs 90102+, and hardware must be 90/92/96. It explains how to supply target.hardware or discover it. It stops short of explicitly naming alternatives like pixoo64_send_items for non-text overlays.

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 a real constraint (works only on hardware profiles 90/92/96), but says nothing about whether the setting persists, what happens on unsupported hardware, or what the call returns. For a device-mutating call this leaves the agent guessing about 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?

Three short sentences, verb and range front-loaded, no filler. The telegraphic phrasing ('Set Channel/SetBrightness') and sentence fragments are slightly terse but cost little.

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 a nested target object, no output schema, and no annotations, the definition covers range and hardware compatibility but omits outcome/return behavior and error cases. Adequate to invoke, thin for a mutation tool with a nested parameter object.

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?

At 50% schema coverage, the description adds some value by restating the 0–100 brightness range and clarifying that target.hardware should be supplied for direct LAN control or resolved via discovery. However, it adds nothing about the nested target fields (host/port/timeoutMs) or the required-vs-optional relationship between target and brightness beyond what the schema already documents.

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?

Names a specific verb and resource (set brightness) plus the accepted range (0–100), and scopes it to PIXOO64 Hardware 90/92/96, which implicitly separates it from the sibling timegate_set_brightness and watchface_set_brightness. The protocol-style prefix 'Set Channel/SetBrightness' is jargon but does not obscure the intent.

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?

Tells the agent how to target the device ('Provide target.hardware for direct LAN use, or resolve it using device discovery'), which is useful operational guidance. It never explicitly states when to pick this over timegate_set_brightness or watchface_set_brightness beyond the hardware gate, so alternative selection 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, the description does useful work: it discloses the device-family restriction, that index 4 blanks the screen, and how target resolution falls back to environment variables. It omits what happens on unsupported hardware, whether the channel selection persists across power cycles, and any error/return behavior for a mutation call.

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

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

Two dense sentences, front-loaded with the operation and its value table before the hardware constraint. Slightly telegraphic but every clause carries 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?

Covers the two things an agent most needs (index meanings, hardware targeting) for a 2-parameter mutation tool with a nested target object. With no output schema and no annotations, it should also say what a successful call returns or changes and how failures surface; that gap keeps it at minimum-plus.

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 50% and the description compensates well for the most important gap: it gives the semantic mapping of every valid index value (0=faces … 4=black screen) that the schema only constrains numerically. It also explains that target.hardware drives direct LAN control, though it does not add to the sub-fields already documented in the schema.

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

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

States a specific verb and resource (set channel/index) and enumerates all five channel meanings, which no other sibling does. It does not explicitly name the analogous sibling (timegate_select_clock), but the 'PIXOO64 Hardware 90/92/96 only' scope effectively separates it from the TimeGate-family 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?

Firmly bounds usage to PIXOO64 hardware 90/92/96 and tells the caller two ways to supply a target (explicit target.hardware vs. device discovery). It stops short of stating when-not-to-use or pointing at a concrete alternative tool for other hardware.

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 carries the full burden. It usefully discloses that custom display-list dials are NOT deleted and that the device has five independent screens, but it omits permission/auth requirements (the localToken) and says nothing about the response or failure behavior.

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

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

Three compact sentences that lead with the action, then the clearing semantics, then the scope caveat and hardware constraint. Dense but front-loaded 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?

With no annotations, no output schema and a nested target object, the description covers purpose, hardware scope and one destructive-vs-non-destructive distinction, but leaves auth expectations and return behavior entirely to inference.

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

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

Schema coverage is 50%. The description adds real meaning for textId (-1 clears all) and implies lcdIndex maps to one of five screens. It says nothing about localToken or the nested target override, leaving half the parameters to 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?

States a specific verb and resource ('Clear animation text') plus the protocol call behind it (Draw/ClearHttpText and LcdId). The TimeGate 400/402 constraint and the 'five independent 128x128 screens' note effectively separate it from the PIXOO64 clear-text sibling, though no sibling is named directly.

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 hardware restriction ('TimeGate Hardware 400/402 only') implicitly routes the agent away from pixoo64_clear_text, and textId=-1 gives a clear usage pattern for clearing everything. However there is no explicit when-to-use vs. when-not guidance or mention of alternatives for partial clears.

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 present, the description carries the full burden and does so well: it discloses divergent execution paths for 400 (native Draw/CommandList) vs 402 (sequential MCP execution), that it stops on failure without retry or rollback, and that earlier commands may have already run — a critical non-atomicity warning. It also states the token is never guessed or fetched automatically.

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?

Six dense sentences, each carrying distinct information (execution model, constraints, failure semantics, hardware scope, resource pointer), with the key caveat about partial execution placed prominently. The leading 'Validate' framing is the only mildly wasteful/misleading element.

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?

Behavioral and hardware coverage is strong, but for a batch executor of up to 40 commands with no output schema, the description never indicates what is returned (e.g., per-command success/failure results) on success or partial failure. That return-shape gap leaves an agent guessing about how to interpret the response.

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

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

The description adds real meaning beyond the 67%-covered schema by enumerating batch constraints (no nested lists, token overrides, unsupported commands) and clarifying that LocalToken lives at the MCP argument level only. It does not restate the 40-item cap or target override semantics, which the schema already handles.

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 a batch whitelist command tool ('Validate the complete whitelist batch before writing') and immediately scopes it to TimeGate 400/402 hardware, which separates it from the per-operation siblings like timegate_send_text or timegate_send_items. The initial verb 'Validate' slightly muddies whether this validates or executes, though 'before writing' and 'earlier commands may have run' clarify it executes.

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 explicit constraints on when the tool applies (TimeGate 400/402 only, no nested lists, token overrides, or unsupported commands) and routes the agent to 'divoom://timegate/guide' for details. It does not explicitly name a sibling alternative for single-command cases, so the 'instead of X' guidance is implied 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?

With no annotations, the description carries the full load and does well: it discloses which internal channel is used per hardware revision, warns that the reference Sys/GetBrightness endpoint returns a hardcoded 100 and is not used, and explains that effective brightness reads 0 while the screen is off. It omits the LocalToken authorization requirement, which lives only in 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?

Five short sentences, each carrying distinct information: verb, per-model read path, a negative fact about the reference API, the screen-off edge case, and the hardware/resource pointer. The core action is front-loaded and nothing is repeated.

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

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

No output schema exists, and the description covers the key return-value nuance (0 when the screen is off) plus device-family limits, which is what an agent needs to interpret the result. It could be slightly more explicit about the return shape or the auth prerequisite, but the essentials are 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 both the target override and LocalToken are already fully documented in the schema. The description adds only the hardware 400/402 constraint, which the schema's hardware enum already conveys. 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?

Opens with a specific verb+resource ("Read brightness") and immediately scopes it to TimeGate Hardware 400/402, which separates it from the watchface_* and pixoo64_* brightness siblings. It never names the alternative tool for other hardware, so the sibling differentiation is implicit rather than explicit.

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

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

Clear context for when this applies: 400 vs 402 read paths, TimeGate-only hardware, and a pointer to divoom://timegate/guide for deeper detail. It does not state the inverse (use timegate_set_brightness to change the value) or what to do on other hardware models, so it stops short of full when/when-not 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 behavioral burden. "Report" implies a read with no side effects and the clause "explicit hardware is a caller override, not a queried device identity" usefully clarifies that an override changes which identity is reported rather than what is discovered on the device. However, it never states read-only/non-destructive explicitly, nor behavior on unreachable hosts or which errors to expect.

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 payoff (what gets reported), then the hardware-override caveat, then the device scope and guide pointer. Three dense sentences with no padding, though the semicolon-joined caveat takes a second read.

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-info tool with a fully described schema and no output schema, the description is largely complete: it names the returned fields and the five 128×128 screen layout. It still omits the read-only guarantee and failure modes, which matters because no annotations exist to cover them.

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 nested target/host/port/model/hardware fields are already well documented and the baseline is 3. The description adds one genuine nuance the schema lacks — that a supplied hardware value is a caller override rather than a queried identity — but says nothing about host, port, model, or timeout semantics.

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+resource: "Report the selected hardware profile, endpoint and per-screen canvas" tells the agent exactly what comes back, and "TimeGate Hardware 400/402 only" scopes it to a device family. It never names watchface_get_device_info or pixoo64_get_device_info, so the agent must infer the sibling split from the tool name alone.

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

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

Usage is implied rather than stated: the agent can infer 'call this to learn the device profile and screen layout before sending content,' and the TimeGate-only scope excludes other families. There is no explicit when-to-use/when-not phrasing or pointer to the sibling info tools, and "Read divoom://timegate/guide" is a reference rather than a routing 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 disclosure burden. It does disclose scope (all five independent 128×128 screens are switched together) and the hardware restriction, but says nothing about auth expectations, whether the state persists, or what happens if some screens fail to respond.

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 terse clauses: action plus parameter meaning first, capability/hardware scope second, reference pointer last. No filler and the critical constraint 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 three-parameter mutation tool with no annotations and no output schema, the description covers what changes, on which hardware, and where to get more detail. Failure behavior and the required localToken are the only meaningful omissions, and the token is handled by the schema.

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

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

onOff is the only required parameter and the schema gives it no description or enum, so "onOff=1 on and 0 off" adds the meaning the schema lacks. The target and localToken semantics are already documented in the schema (67% coverage), so the description doesn't need to repeat them.

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?

Names a concrete verb and resource ("Switch all screens") and immediately scopes it to TimeGate Hardware 400/402, which distinguishes it from the pixoo64_onoff_screen and watchface_onoff_screen siblings. It never names the alternative to use for other hardware, so it stops just short of a clean 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?

"TimeGate Hardware 400/402 only" is an explicit precondition for use, and the pointer to divoom://timegate/guide gives the agent further context. There is no explicit when-not statement or named fallback tool, but the hardware gate effectively excludes the non-applicable cases.

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 and mostly does: it discloses that the device downloads the URLs itself, that an acknowledgement does not verify rendering (a genuinely useful caveat implying a snapshot check), and the square 16/32/64/128 dimension constraint. It does not cover the localToken auth prerequisite or failure/rate behavior, which the schema only partially supplies.

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?

Tight and front-loaded: the action comes first, then constraints, then the doc pointer. Sentences are dense and information-bearing, though the run-on layout and the trailing guide reference make it slightly harder to scan than a bulleted constraint list.

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

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

For a no-annotation, no-output-schema mutation tool, the description covers the key risk (ack ≠ rendered) plus hardware and asset constraints. Remaining gaps — authentication via localToken is only in the schema, and no description of what a successful response contains — are minor but non-zero.

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 75%, and the description adds meaning the schema lacks: the square-dimension rule for URLs (schema only enforces count 1–9) and the framing of lcdArray as selecting among five independent 128×128 screens. target/localToken semantics are left to the schema, which is reasonable given their descriptions.

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

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

States a specific verb and resource ('Play 1–9 HTTP GIF URLs on the selected screens using Device/PlayGif') and immediately narrows scope to TimeGate Hardware 400/402, which is what separates it from pixoo64_play_gif and the send_text/send_items siblings. An agent can pick this tool 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?

The hardware gate ('TimeGate Hardware 400/402 only') and the pointer to divoom://timegate/guide give clear conditions for use. It stops short of naming the sibling to use for other hardware (pixoo64_play_gif) or explaining when to choose GIFs over timegate_send_items/timegate_send_text.

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 does surface a genuinely non-obvious behavioral rule (lcdIndependence must come from the existing device configuration, no default is assumed) and the hardware gate, but it never states that this changes device state, whether the selection persists across reboots, or what errors occur when lcdIndependence mismatches.

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

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

Four short sentences, front-loaded with the primary selection rule, then the per-screen case, then the hardware constraint. No filler; the guide reference is a single useful pointer rather than 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?

For a 5-parameter, nested-target, no-output-schema, no-annotation mutation tool, the definition leaves out where clockId comes from, what the call returns, and any error/permission behavior. The hardware and independence notes are helpful but the required parameter's provenance is unexplained.

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

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

Schema description coverage is only 40%, and the most important gap is clockId — the sole required parameter, which has no schema description and no explanation in the description (presumably an ID from the clock catalog). The description does add real meaning for lcdIndex (omitted = whole device) and lcdIndependence (must match existing config), partially compensating.

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?

A specific verb+resource ("Select a whole-device clock") with the scope condition stated up front (when lcdIndex is omitted) and a hardware applicability limit (TimeGate 400/402). It is not, however, differentiated from the sibling watchface_set_clock_select, which the agent may plausibly confuse with this 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?

Explicit usage branches are given: omit lcdIndex for whole-device selection, or supply lcdIndex plus lcdIndependence for a single screen, and it warns that no default independence ID is assumed. It lacks an exclusion or pointer to the nearest alternative (watchface_set_clock_select, timegate_command_list for discovering clockId).

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 this description carries the full burden and does well: it warns that missing background data can block visible rendering despite a success acknowledgement, that the MCP does not download the background, and that 400 documentation says background is ignored on replace. It still omits auth/token behavior and any rate or timeout 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?

Dense and front-loaded: tool purpose first, then mode semantics, then background caveats, then hardware scope. Some sentences are terse to the point of being cryptic ('400 documentation says background is ignored on replace'), but nothing is 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?

With no output schema and no annotations, this is a fairly complete brief for a nested-parameter device write tool: it covers the hardware restriction, background requirement, mode semantics, and points at the divoom guide. The auth requirement for localToken relies on the schema rather than the description, which is a minor residual 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 50%, and the description meaningfully fills gaps: mode maps to NewFlag=1/0, backgroundGif is a device-accessible HTTP GIF URL under 256 bytes needed to initialize a 402 screen, and the 400/402-only hardware restriction explains the lcdIndex 0-4 range. items and target details are left wholly to the schema.

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

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

States a specific verb and resource: 'Create or update one screen with Draw/SendHttpItemList', and scopes it to TimeGate 400/402. Clear enough that an agent knows this is the screen-layout write path, though it never explicitly contrasts with timegate_send_text or timegate_play_gif.

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 concrete mode-selection guidance (replace vs append) and says when backgroundGif is required (first use of a 402 screen). But it does not say when to pick this tool over timegate_send_text or timegate_play_gif, so a sibling choice 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 at all, the description carries the full burden and does disclose hardware-conditional behavior (400 sends LcdIndex; 402 reads LcdId), font/height constraints (fonts 0–7, 16-pixel height independent of display-list fonts), and device scope. It does not say what happens when a TextId slot is reused, whether it overwrites existing text, or how errors surface.

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

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

Front-loaded with the action and constraint, then hardware and font notes and a pointer to the guide; every sentence carries technical content. The telegraphic phrasing ('400 sends LcdIndex; 402 source reads LcdId') is dense to the point of being cryptic but wastes no space.

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

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

For a mutation tool with no annotations, no output schema, and nested parameters, the description covers device gating, prerequisites, font/height rules, and a fallback reference document. Missing pieces are slot/overwrite semantics for TextId and how text is removed afterward (timegate_clear_text is unmentioned).

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?

At 50% schema coverage, the description clarifies lcdIndex (must be the animation's first selected screen) and constrains font to the animation range, which the schema only bounds numerically. However, TextId (0–19 slot semantics), TextWidth, x/y, dir, align, speed, and color get no explanation in either schema or description. Baseline 3 for partial compensation.

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 ('Add text to an already active HTTP animation') and immediately scopes it to TimeGate 400/402 hardware with five 128×128 screens. It explicitly contrasts itself with the sibling alternative send_items type 22 for regular custom dials, so an agent can pick the right tool 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?

Provides a real prerequisite ('already active' animation, lcdIndex must be the first selected screen) and names the alternative for the other case (send_items type 22 for regular custom dials). It stops short of exclusions such as when to use timegate_clear_text or what to do when no animation is running, so it is clear but not exhaustive.

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, so the description carries the full load. It usefully discloses that the setting is global across the five independent 128×128 screens, but says nothing about persistence, what brightness 0 does (screen off vs. dim), required token/auth, or discovery/timeout behavior during the call.

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

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

Three compact clauses with the core action front-loaded and no filler; the hardware qualifier and guide pointer follow in logical order. The 'five independent 128×128 screens' fragment is slightly telegraphic but still 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 mutation tool with no annotations, no output schema, a nested target object and a required localToken, the description covers the device scope but leaves mutation side effects, token requirement, and target-override behavior entirely to the schema. Enough to call it, not enough to call it confidently.

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 0–100 range is already enforced by the schema's minimum/maximum, so restating it adds nothing, and the description says nothing about target/model/hardware selection or when localToken is needed. Schema coverage is 67%, which is adequate, so baseline 3 applies.

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

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

States a specific verb and resource (set global LCD brightness) plus the value domain (0–100), and immediately scopes it to TimeGate Hardware 400/402, which cleanly separates it from the sibling pixoo64_set_brightness and watchface_set_brightness.

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 hardware restriction ('TimeGate Hardware 400/402 only') tells the agent when this tool applies and implicitly rules it out for PIXOO64/other devices, and it routes to divoom://timegate/guide for more detail. No explicit negative case or named alternative tool, so just 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 must carry the full behavioral burden, and it does disclose unusually valuable context: the data's provenance (generated from both simulator clocksys directories), the meaning of the default set (Device/GetClockDefaultList with IsDefault=1), and that TimesFrame data is independent. It stops short of stating that the call is read-only and never mentions rate limits or response shape, but the provenance and prerequisite chain are exactly the kind of info annotations could not supply.

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 returned-field inventory is front-loaded in sentence one, with conditional model caveats following, so an agent can stop reading early if it's on TimesFrame. It is somewhat dense with internal jargon (clocksys, Device/GetClockDefaultList) and the AstroToo/TimesFrame threading could be tighter, but no sentence is 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 an 11-parameter tool with a nested target object, no output schema, and no annotations, the description supplies the two things an agent most needs: what rows contain and model-specific caveats. With full schema coverage on filters and defaults, the remaining gap (no explicit statement that the operation is read-only, no pagination behavior beyond the limit param) is minor.

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; the description still earns a point by explaining what 'default' actually means for defaultOnly (the Device/GetClockDefaultList IsDefault=1 set) and by reinforcing that model is for offline authoring only. Filters like disps/fonts/tagsAny are covered only by their schema text, which is adequate given full coverage.

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

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

The first sentence names a specific verb (query) and enumerates exactly what the tool returns: ClockId, Chinese/English names, font ids, disp ids, item ids, and optional source configuration. That is far more informative than a tautology, though it never names the sibling catalogs (watchface_font_catalog, watchface_disp_catalog) that overlap with the font/disp fields, so differentiation is left to inference.

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

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

There are real prerequisites ('For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources') and a scope restriction ('Legacy 800x1280 examples and typography apply only to TimesFrame'), which is more than most tools offer. However, there is no guidance on when to use this catalog instead of watchface_font_catalog or watchface_disp_catalog, even though both presumably cover a subset of these fields.

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 well: it discloses that the server injects ClockId, reads the slot first, creates only when missing, and otherwise updates. It also lists hard rejections (AstroToo rejects TAR/TGZ/ZIP, UseDialAssetBundle!=0, bundle_image) and file constraints (<500 KiB, 480x480 vs 800x1280).

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?

Information-dense and front-loaded with the upsert semantics. Slightly hurt by run-on sentences and the repeated 'For AstroToo' framing that could be consolidated, but every sentence carries substantive constraints.

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

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

For a mutation tool with no annotations and no output schema, the description covers the required preconditions, per-model constraints, injected values, and rejection cases. An agent has enough to invoke it correctly on either model family.

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 a baseline 3 applies, but the description adds real meaning beyond the schema: callers must not provide ClockId, metadata DialAssets must be 'image' for AstroToo with local:// image_addr values, and imagePath dimensions differ per model.

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

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

Opens with a specific verb+resource: 'Upsert the MCP-managed local watchface with multipart.' It also distinguishes the operation from sibling tool watchface_upload_file, which it correctly positions as a prerequisite for element uploads rather than an 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?

Gives explicit model-specific workflows: 'For AstroToo, first query hardware/capabilities' and 'upload every element separately with watchface_upload_file... then call this tool.' It doesn't explicitly contrast with watchface_patch_local or watchface_replace_dial_bg_file, so there's no explicit when-not clause, but the prerequisites are 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?

No annotations are provided, so the description carries the full burden and it adds meaningful behavior: it distinguishes TimesFrame and AstroToo enums, names AstroToo return fields, mandates a hardware/capabilities lookup first, and warns that legacy 800x1280 examples apply only to TimesFrame. It stops short of stating read-only safety or response/pagination behavior, but for a catalog query it provides solid context.

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

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

The description is front-loaded with the core action and then adds model-specific constraints and prerequisites. It is four sentences with little filler, though the jargon and dense phrasing reduce readability slightly.

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 has 12 parameters and no output schema, so the description should do more to explain return shape and row structure. It mentions AstroToo entry fields and `idsOnly` compact rows, but does not fully describe the default output or TimesFrame return values, leaving the agent to infer the catalog response format.

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 explains all 12 parameters, including the nested target object and filter enums. The description adds some value by clarifying `model` as offline-authoring-only and by tying the catalog to `ItemList[i].disp` and `ItemPatchList[i].patch.disp`, but most parameter meaning is already in 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 states a specific verb and resource: return the selected product's `disp` catalog for `ItemList[i].disp` and `ItemPatchList[i].patch.disp`. It is clearly a catalog lookup, though the term `disp` is jargon and it does not explicitly distinguish itself from sibling catalogs such as `watchface_font_catalog` or `watchface_clock_catalog`.

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 useful context for AstroToo, instructing the agent to first query hardware/capabilities and use 480x480 resources. However, it does not state when to use this tool versus the clock/font/template catalog siblings, nor does it describe explicit exclusions or alternatives beyond the model split.

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 and does so well: it discloses that results are curated rather than authoritative (the on-device list may be a subset) and enumerates the response fields including the `scenarios` map. It stops short of stating whether filters combine or how `limit` truncation behaves, which leaves a small residual unknown.

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 purpose and return shape, then the caveats, which is the right order. The trailing AstroToo/480x480 and TimesFrame 800x1280 notes are relevant but slightly verbose for a catalog tool and dilute the core message.

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?

Ten parameters including a nested `target` object and no output schema, yet the description compensates by describing the returned fields and the `scenarios` map in detail. Remaining gaps (filter combination semantics, truncation) are minor given that the schema documents each parameter.

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 `ids`, `tag`, `scenario`, `idsOnly`, `includeScenarios`, and the nested `target` object. The description only restates the high-level purpose of the filters ("Use the optional filters to narrow the result") without adding syntax or interaction semantics, so it does not meaningfully exceed 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?

States a specific verb and resource ("Return a curated font catalog") plus the exact entry fields returned, so the agent knows the payload shape before calling. It explicitly separates itself from `watchface_get_fonts_local` (on-device subset) and from the visual guide resource, which are the closest siblings.

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 explicit when-to-use routing: read `divoom://font/guide` first for visual style, cross-check with `watchface_get_fonts_local` before committing a font id to a real device, and query hardware/capabilities first for AstroToo. It also names the exclusion (legacy 800x1280 examples apply only to TimesFrame).

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 carries the full behavioral burden. It discloses the AstroToo prerequisite but omits what the call actually returns, whether it fails on unsupported hardware, and how errors surface. The 480x480 resources and typography remarks add no behavioral information for a read of brightness.

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

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

It is short, but the lead is an opaque API path rather than a plain statement of purpose, and the 480x480 and typography sentences are irrelevant to a brightness read. Those sentences do not earn their place and push the reader away from the actual task.

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

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

There is no output schema and the description never explains the return value (a brightness value, its range, or format), which is the central thing an agent needs. For a getter with a nested target parameter and no annotations, the definition is under-specified.

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

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

Schema description coverage is 100% and the single nested 'target' object is fully documented, so the baseline is 3. The description's AstroToo/TimesFrame note loosely maps to target.model but adds no syntax or fallback detail beyond the schema.

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

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

The description names a concrete endpoint (Sys/GetBrightness) that implies reading the device's current brightness, but it never states in plain language that this returns the current brightness level. It also does not distinguish itself from siblings like timegate_get_brightness or watchface_get_device_info, leaving the agent to infer which getter to call.

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 one real precondition for the AstroToo path (query hardware/capabilities first), which is useful. However, there is no guidance on when to use this over timegate_get_brightness or watchface_get_device_info, and no exclusions or context for the default 'auto' model.

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 adds useful behavior: unknown Hardware is rejected, PIXOO64/TimeGate rely on discovery or explicit hardware profiles, and AstroToo needs a capability query first. But it does not explicitly state that the operation is read-only, nor does it describe auth needs or response 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?

The description is front-loaded with the core purpose and then layers device-specific caveats efficiently. It is dense but mostly justified for a multi-device tool; the final sentence about legacy 800x1280 examples is somewhat tangential but still clarifies context.

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

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

Given one optional nested parameter with full schema coverage and no output schema, the description covers device routing and hardware validation well. However, it describes the return value only generically as 'product profile and LAN capabilities' and omits read-only/safety context that would be important without annotations.

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 target.host, port, model, hardware, and timeoutMs. The description adds meaning by clarifying that target.hardware is a device profile rather than firmware, and by explaining model-specific routing, but it does not add syntax or examples 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 opens with a specific verb and resource: 'Return the product profile and LAN capabilities.' It also distinguishes device families (TimesFrame/AstroToo vs PIXOO64/TimeGate), though it does not explicitly name sibling tools like pixoo64_get_device_info or timegate_get_device_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?

It gives some procedural guidance, such as 'For AstroToo, first query hardware/capabilities' and 'Unknown Hardware is rejected.' However, it does not clearly state when to use this unified tool versus the device-specific siblings, leaving the agent to infer the routing decision.

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 it does disclose one meaningful trait: output depends on device model (AstroToo 480x480 resources vs. legacy TimesFrame 800x1280). However, it never states that this is a read-only retrieval, what happens on an unreachable device, or how results are shaped, which is a notable gap for an unannotated 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?

Three tight sentences with no filler, front-loaded with the endpoint being invoked. It is dense and slightly cryptic in phrasing ('Legacy 800x1280 examples and typography apply only to TimesFrame'), but every sentence carries model-specific 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 read tool with no annotations, no output schema, and a nested target object, the description covers model selection and a discovery prerequisite but omits return-value shape, read-only safety, and fallback behavior. It is minimally sufficient to attempt a call but leaves an agent guessing about 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?

Schema description coverage is 100% and every nested target field (host, port, model, hardware, timeoutMs) is documented in the schema itself, so the baseline applies. The description adds only a model caveat that acts more as a workflow instruction than parameter clarification, and does not explain how target.model/hardware interact with this specific call.

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 leads with the underlying endpoint name 'Device/GetLocalFontList', which implies retrieving the font list from the device, but it never states in plain language what the tool returns or how it differs from the sibling watchface_font_catalog. An agent can mostly infer purpose from the tool name plus endpoint, so it is adequate but not self-evidently distinguished from alternatives.

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

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

The only usage guidance is model-conditional ('For AstroToo, first query hardware/capabilities') and a scoping note that legacy 800x1280 assets apply only to TimesFrame. There is no statement of when to use this versus watchface_font_catalog or watchface_get_local, and no exclusion conditions for callers.

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 behavioral burden. It adds useful non-obvious context about AstroToo requiring a hardware/capabilities query and TimesFrame-specific legacy resources, but it does not explicitly confirm read-only behavior, describe authentication needs, or state what is returned.

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

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

The description is concise and front-loads the main operation before adding platform-specific caveats. The device-specific details are specialized but relevant, and there is little 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 5-parameter tool with no annotations, low schema coverage, and no output schema, the description is too thin. It provides platform caveats but does not explain return values, parameter behavior, or enough mutation/read semantics for an agent to call it confidently.

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

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

Schema description coverage is only 20%, so the description must compensate. It mentions current or explicit clock id, loosely mapping to clockId/useCurrentDisplayClock, but adds no meaning for parentItemId, parentClockId, or the distinction between them, and leaves most top-level parameters undocumented.

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 references the underlying API endpoint Device/GetLocalClockInfo and mentions current or explicit clock id, implying retrieval of local clock information. However, it does not plainly state the user-facing outcome and relies on the reader understanding the internal endpoint name, leaving the purpose somewhat vague relative to siblings like watchface_get_device_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?

It provides platform-specific prerequisites for AstroToo and resource guidance for TimesFrame, but does not say when to use this tool versus alternatives such as watchface_get_device_info or watchface_list_devices. There is no explicit when-to-use or when-not-to-use 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 burden and does well: it discloses the two-step flow (send Device/GetScreenSnapshot, then HTTP GET the returned snapShotPath), that the path is validated, that the format is currently BMP with a WebP fallback on TimesFrame, and that savePath writes a file locally. It does not cover failure behavior (unreachable device, invalid path) or whether savePath's directory must exist, 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 purpose and the action sequence are front-loaded, and the device-specific caveats follow in a logical order. It is dense and slightly run-on (legacy 800x1280 typography note is tangential), but nearly every sentence carries operational 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 tool with no annotations, no output schema, and an all-optional parameter set, the description explains the flow, the return artifact (downloaded/validated image), format differences, and the hardware prerequisite. Remaining gaps are error handling and local path requirements, which are secondary.

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 all four parameters (including the nested target object) are already documented in the schema; baseline is 3. The description adds only marginal nuance, e.g. that AstroToo always uses the response snapShotPath while snapshotHttpPath is a TimesFrame-only fallback, which the schema largely states too.

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 ('Capture the rendered screen') and states the reason ('visual verification after create/patch/switch'), plus names the underlying protocol call Device/GetScreenSnapshot. No sibling tool captures a screen, so an agent can immediately tell this is the post-mutation verification tool rather than a catalog/info 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?

It gives a clear usage trigger ('after create/patch/switch') and an explicit prerequisite ordering for AstroToo ('first query hardware/capabilities; use the 480x480 AstroToo resources'). It stops short of naming when-not-to-use or an alternative tool, but the sequencing guidance is concrete.

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 does disclose a genuine behavioral dependency (requires prefetch to have populated in-memory store data) and model-specific resource constraints (480x480 for AstroToo, 800x1280 legacy only for TimesFrame), which is useful. But it omits whether this is purely read-only, what the response shape is, pagination, and any failure modes when prefetch has not run.

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

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

Three short sentences with little waste, but the lead is an internal endpoint name rather than the user-facing purpose, so the most important information is not front-loaded. The model-specific trivia (480x480, legacy 800x1280 typography) crowds out a plain statement of what the call yields.

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

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

There is no output schema, so the description is the only place the return value could be explained — yet it says nothing about what the store market list contains or how to consume it. For a zero-required-parameter read tool whose result the agent must act on, the omission of return semantics is a significant gap despite the decent environment/prerequisite 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?

Schema description coverage is 100%, including nested host/port/model/hardware/timeoutMs docs, so the schema does the heavy lifting and baseline 3 applies. The description adds only an oblique hint that hardware/capabilities should be queried first, which loosely maps to target.model/target.hardware, but it adds no syntax or 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 points at the underlying endpoint (Device/GetStoreClockMarketList) and the tool name implies a store/market listing, but it never states in plain terms what the tool returns (e.g. a list of downloadable clock faces). It is a procedural pointer rather than a purpose statement, and it does not distinguish itself from siblings like watchface_clock_catalog or watchface_template_search.

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 real precondition ('after device prefetch has populated in-memory store data') and a model-specific prerequisite ('For AstroToo, first query hardware/capabilities'), which is more than most. However, it never says when NOT to use it or which sibling catalog/search tool to prefer, so the agent still has to guess at 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, the description carries the full behavioral burden and does well: it discloses that outputs are soft guidance, not firmware-enforced, and that boxes must be clamped to the logical canvas. It also explains model-dependent behavior and hardware checks. It stops short of describing error behavior or whether results are deterministic, but is substantially more informative than typical.

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 action and then layers usage constraints and model caveats efficiently. It is dense but appropriately sized for a tool with nested target parameters and model-specific behavior. A slightly tighter opening sentence could improve it, but there is very little 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?

The tool has no output schema and five parameters including a nested target object, so the description needs to explain return content and usage context. It does so by naming the typography fields aggregated (median size/x/y/w/h, frequent colors, alignment mode) and by giving model-specific guidance. It is nearly complete, though it does not describe response shape or failure modes in detail.

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. The description adds meaningful cross-parameter context beyond the schema: the model affects which resources apply, AstroToo requires a hardware/capabilities query first, and canvas width/height serve clamp reminders. This helps an agent reason about parameter interactions rather than just field meanings.

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: 'Return layout hints for a single disp id' by combining disp-catalog metadata with aggregated typography from marketplace templates. It clearly distinguishes the tool from siblings like watchface_template_search and watchface_disp_catalog by describing the unique synthesis it performs.

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 to use this 'before authoring a new ItemList row or ItemPatchList.patch fragment' and clarifies that values are 'soft guidance, not firmware-enforced.' It also gives model-specific routing: for AstroToo, first query hardware/capabilities and use 480x480 resources; legacy 800x1280 examples apply only to TimesFrame.

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 does disclose that this is a network fetch against a specific cloud endpoint and that non-matching hardware is silently filtered out. It does not cover auth/network requirements, latency, failure modes, or what the discovered entries look like, which matters for a discovery tool with no output 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?

Three tightly packed sentences with the core capability and supported hardware front-loaded, followed by scope and port notes. The port sentence is awkwardly worded but not 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?

For a zero-required-param discovery tool with no annotations and no output schema, the agent still needs to know the shape of the returned device list (names, model identifiers, LAN vs cloud) and the meaning of timeoutMs. The description covers supported hardware and the source endpoint but leaves the return contract and one of two parameters unexplained.

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 only 50%: `port` is documented well in the schema, but `timeoutMs` is undocumented anywhere except its 45000 default, and the description never explains what it times out or what happens on expiry. The sentence 'PIXOO64/TimeGate targets include Hardware and version-specific ports' is vague and reads more like return-value commentary than parameter guidance, so it fails to compensate for the coverage gap.

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

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

States a concrete verb (List) and resource (selectable devices), enumerates the exact supported model families, and names the upstream endpoint. It is clearly distinguishable from siblings like watchface_get_device_info, which target a single device.

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: you call this to discover devices before targeting them with the per-model tools. However, there is no explicit 'use this when...' statement, no ordering guidance (e.g., call before get_device_info), and no when-not condition beyond the hardware filter.

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 disclosure burden, and it leaves most of it unaddressed: no statement of side effects, required auth, rate limits, failure modes, or what a successful response looks like. The device-routing notes are useful context but are about target selection, not about behavior of the operation itself.

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

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

Two short sentences, front-loaded with the core operation, which is good. But the trailing clause about 'Legacy 800x1280 examples and typography' is largely irrelevant to a screen-power toggle and spends the description's limited budget on tangential asset guidance.

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

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

For a mutation tool with no annotations and no output schema, the description should at least indicate the nature of confirmation/response. It does supply the multi-device routing context needed to call the nested target correctly, but stops short of covering outcomes or errors.

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 explains onOff, host, port, model, hardware, and timeoutMs thoroughly; the description's '1=on, 0=off' merely restates the enum. It does add marginal meaning by tying model choice to resource dimensions ('480x480 AstroToo', '800x1280 ... only to TimesFrame'), so baseline 3 holds.

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 and resource: 'Call Channel/OnOffScreen with OnOff (1=on, 0=off)', which tells an agent exactly what happens (screen power state change). It also scopes model behavior (AstroToo vs TimesFrame legacy), though it never explicitly distinguishes this tool from the dedicated pixoo64_onoff_screen and timegate_onoff_screen siblings.

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 one real procedural prerequisite: 'For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources.' However, there is no guidance on when to pick this generic tool versus the model-specific on/off siblings, which is the most likely selection confusion for an agent.

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

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

With no annotations, the description carries substantial behavioral burden and discloses server-injected ClockId handling, read-then-update/create logic, endpoint selection, and device-specific asset restrictions. Remaining gaps include explicit overwrite semantics, error behavior, and what the tool returns.

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

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

The description is dense but front-loaded, beginning with the core upsert behavior before moving into device-specific constraints. Most sentences earn their place, though the single-paragraph format could be structured more clearly for a complex 12-parameter tool.

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

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

The description covers the main workflow and important TimesFrame/AstroToo constraints, but it is not fully complete for a 12-parameter tool with no output schema and only 33% schema description coverage. Several optional parameters and return behavior remain undocumented.

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 low at 33%, so the description must compensate for many parameters. It adds useful meaning for dialAssetsPath, ItemList, ItemIdList, itemPatchList, and ClockId, but leaves setColorList, itemPatchByRoleList, deviceImageUrl, and preview image parameters unexplained.

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

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

The description states a specific verb and resource: 'Upsert the MCP-managed local watchface.' It clarifies the server-managed ClockId and update-vs-create behavior, making the operation distinct from a plain create/read tool, though it does not explicitly name sibling tools such as watchface_create_local_clock.

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 operational guidance: field-only updates use POST /divoom_api, asset updates use multipart, ItemPatchList is preferred for existing rows, and AstroToo requires querying hardware/capabilities first. It does not explicitly compare itself to alternative siblings like watchface_create_local_clock or watchface_replace_dial_bg_file.

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 full burden. 'Return' implies a read-only lookup and the model-applicability notes add real context, but the description never describes what the returned constraints actually contain or their format, which is a meaningful gap for a no-annotation, no-output-schema 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?

Two sentences, front-loaded with the purpose and followed by model-specific caveats. Efficient, though the second sentence packs two distinct conditional rules that could be clearer.

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 2-param reference tool with full schema coverage and no output schema, the description covers purpose and model scoping but is vague about the actual content and structure of the returned constraints, leaving the agent unsure what it will receive.

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 the model enum and nested target object fully documented in the schema. The description's mentions of AstroToo/TimesFrame loosely map to the model parameter but add little syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource: returns 'concise operational constraints extracted from the public guide and skill.' An agent can grasp this is a reference-lookup tool. However it doesn't clearly differentiate itself from sibling reference tools like watchface_command_list or pixoo64_command_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 model-conditional guidance ('For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources' and legacy constraints apply only to TimesFrame), which is useful context. But it never states explicitly when to call this tool versus the sibling command_list/reference tools, leaving selection 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?

No annotations, so the description carries the burden and does disclose some traits: payload is merged with an enforced ReturnCode=0, and certain payloads are restricted to ClockId 60000. However, it does not describe failure/error behavior, permissions, or the risk profile of a raw low-level command, which matters for a tool with no safety 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?

Front-loads the core purpose, then layers restrictions, alternatives, and platform notes in subsequent sentences. Dense but each sentence adds relevant context. The AstroToo and TimesFrame notes are useful though slightly tangential to the core call mechanics.

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 raw command tool with no annotations and no output schema, the description covers scope, restrictions, and platform guidance well. It still omits return format and failure behavior, which an agent must guess for a low-level passthrough that can produce varied responses.

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 33%: 'command' and 'payload' have no schema descriptions, but the description compensates by stating command is required and that payload is merged with ReturnCode=0 and constrained for certain commands. The nested 'target' fields are already well documented in the schema. Partial compensation justifies a middle score but not higher, since command syntax and payload structure remain underspecified.

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: a raw wrapper around POST /divoom_api. It distinguishes itself from siblings by pointing to the dedicated create/patch tools for the full flow, so an agent can tell it is the low-level escape hatch. Not quite a 5 because 'raw command wrapper' still leaves the exact command space somewhat open.

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 when-to-use constraints: ClockId 60000 restriction on raw Create/PatchLocalClock, use dedicated create/patch tools for the full precheck and multipart flow, and query hardware/capabilities first for AstroToo. These are explicit alternatives and preconditions. Lacks a blanket 'prefer dedicated tools when one exists' exclusion, keeping it from 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?

No annotations exist, so the description carries the full burden, and it does substantial work: it discloses that only the cached bitmap is replaced, that archives are rejected, and that the payload must be JPEG/WebP under 500 KiB. It omits whether the replacement is reversible, permission/auth requirements, and failure behavior, keeping it short of a 5.

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

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

The most important constraint (what the endpoint does and what it refuses) is front-loaded, and most sentences carry a constraint rather than filler. The trailing 'Legacy 800x1280 examples and typography apply only to TimesFrame' is cryptic and partially redundant with the dimension rules stated earlier.

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 six-parameter mutation tool with no annotations and no output schema, the description covers hardware targeting, format, and size but leaves clockId, useCurrentDisplayClock, and the response shape unaddressed. It is workable for a confident caller but leaves real gaps for one unfamiliar with the device family.

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 sits at 67%, and the description's parameter-adjacent content (image format, size, TimesFrame 800x1280 / AstroToo 480x480) largely repeats what the imagePath schema field already says. Two parameters, clockId and useCurrentDisplayClock, are undocumented in both the schema and the description, leaving the agent to guess at their 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 names a specific operation (replacing the cached dial bitmap) plus the exact endpoint and transport (POST /replace_clock_dial_bg, multipart). The clause 'does not accept archives' implicitly separates it from the generic upload sibling, but no sibling is named explicitly, so differentiation rests on inference.

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

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

It gives a real precondition workflow ('For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources'), which is useful ordering guidance. However, it never states when to use this tool instead of watchface_upload_file or watchface_create_local_clock, and gives no when-not 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 full burden and does disclose a critical behavior: local sys-side files are deleted. That is a genuine safety-relevant disclosure. But it leaves the 'optional cloud refresh' undefined (no parameter appears to control it), and says nothing about reversibility, permissions, or failure modes.

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 gross padding, and the destructive effect is stated early. But the leading 'Call Device/ResetLocalClockFromServer' restates the tool name, and the TimesFrame typography note is tangential to invocation.

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 nested-schema, no-annotation, no-output-schema mutation tool this is thin. Key identifiers (clockId, parentItemId, parentClockId) are unexplained, the 'optional cloud refresh' trigger is opaque, and there is no return-value or error guidance to compensate for the missing 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?

Schema coverage is only 25%: clockId, parentItemId, and parentClockId have no descriptions anywhere. The description mentions hardware querying for AstroToo (loosely mapping to target.model/hardware) but explains none of the three top-level identifiers, which are the parameters an agent actually must supply.

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 concrete operation (Device/ResetLocalClockFromServer) and adds the key effect: it deletes local sys-side files before an optional cloud refresh. However, the verb is buried in a protocol path, and nothing distinguishes this from siblings like watchface_get_local or watchface_patch_local. An agent has a rough idea of the action but must infer the 'reset' semantics.

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 a device-specific precondition (query hardware/capabilities first for AstroToo, use 480x480 resources) but never says when to choose this tool over alternatives or when not to use it. The destructive reset vs. non-destructive patch/list siblings are not routed at all.

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 must carry the behavioral burden, and it does disclose a device-specific prerequisite flow (AstroToo capability query) and model/resource differences. It omits critical traits such as the accepted brightness range/units, whether the setting persists across power cycles, and what permission or connection assumptions apply, leaving significant gaps for a mutation 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?

Only three sentences with little waste, but they are jargon-heavy and front-load an internal protocol path ("Call Channel/SetBrightness") instead of the primary effect. The device-specific caveats read as scattered notes rather than a structured usage statement.

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 mutation tool with no output schema, the description should at minimum pin down the brightness value domain and the environment-variable fallback for an omitted target. Neither is covered, and the target defaults (port 80 vs 9000, model 'auto' behavior) are left solely to the schema.

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

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

Schema coverage is 50%, and the uncovered parameter is the most important one: 'brightness' has no schema description and the prose only says "with Brightness", giving no range, units, or clamping behavior. The 'target' object is well documented in the schema, so the description adds essentially nothing beyond structured fields.

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 verb is framed as a protocol call ("Call Channel/SetBrightness") rather than a plain statement like "set device screen brightness", so the agent must infer the intent from the tool name. The resource is named and 'brightness' is identified as the payload, but it does not clearly distinguish this generic setter from siblings like pixoo64_set_brightness or timegate_set_brightness.

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 conditional prerequisites for AstroToo (query hardware/capabilities first, use 480x480 resources) and notes that legacy 800x1280 examples apply only to TimesFrame, which is useful device-scoping context. However, it never states when to use this umbrella tool versus the model-specific set_brightness siblings, leaving routing entirely 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, the description carries the full burden and does add real behavioral detail: the queued duplicate request on TimesFrame, its side effect of suppressing an active traditional clock schedule for the current period, and single-send behavior on AstroToo. It still omits failure modes and whether the change is persistent or reversible.

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

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

Three sentences, front-loaded with the operation call, then device-specific behavior, then resource guidance. Dense but every clause carries information; only the trailing 'legacy 800x1280' sentence feels tacked on.

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

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

For a multi-device select operation with no annotations and no output schema, the description covers the important device divergence but leaves gaps: the source and validation of clockId, sysUpdateTime's effect, and what a caller gets back on success or failure.

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 67% and clockId — the one required parameter — has no schema description; the description only repeats 'with ClockId' and never explains where to obtain a valid id (e.g., via watchface_clock_catalog). The nested target fields are already well documented in the schema, so the description adds little beyond 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 first sentence names the concrete protocol operation (Channel/SetClockSelectId) and its key argument (ClockId), which maps to a specific verb-and-resource. However, it never plainly states in user terms that this activates a clock face on a device, and it does not distinguish itself from the sibling timegate_select_clock.

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 useful device-specific context: on TimesFrame the request is queued as a pair to suppress an active traditional clock schedule, on AstroToo it is sent once, and AstroToo requires first querying hardware/capabilities. But it never says when to choose this over timegate_select_clock or watchface_raw_command, nor which clockId sources are valid.

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 carries the full burden, and it discloses the library size and provenance, the tag vocabulary, the effect of includeWatchface=false, and model-specific resource caveats. It never states the return payload shape or that results are read-only/static, 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?

Information is front-loaded with the library identity before filter and device caveats, and nearly every clause adds new detail. It is dense and slightly long, but no sentence is 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 12-parameter tool with a nested target object, no annotations, and no output schema, the description supplies the missing behavioral context (corpus, filters, model-specific resources, compact mode). It omits explanation of the target/model/nameContains parameters and of returned template fields, but the rich schema offsets much of that.

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 defines every parameter; the description merely enumerates the filter families (tagsAll/tagsAny, bucket, clockIds, item-count bounds, dispPresent) without adding semantics beyond the schema. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

States a specific verb and resource (search the curated template library at divoom://templates/curated) and quantifies the corpus (~20 marketplace-derived watchface skeletons) with example tags. It also positions the tool against the sibling layout_suggest tool by advising 'prefer cloning an existing ItemList layout before inventing raw coordinates'.

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 actionable context: use includeWatchface=false for a compact summary, query hardware/capabilities first for AstroToo and use 480x480 resources, and treat legacy 800x1280 examples as TimesFrame-only. It does not name explicit when-not-to-use cases or sibling alternatives by name, so it falls just 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 provided, the description carries the full behavioral burden and does so thoroughly: it explains the temporary local:// FileId return, atomic move into durable storage on binding, cleanup of unbound uploads on reboot, and the guarantee that unbound uploads are never sent outward. It also discloses rejected archive formats and prerequisite hardware/capability checks.

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 definition is front-loaded with the core action and is dense with relevant constraints rather than filler. It is somewhat long and run-on for a single paragraph, but each sentence contributes routing, lifecycle, or prerequisite information useful to an agent.

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

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

For a complex upload tool with no annotations and no output schema, the description is largely complete: it covers routing, binding lifecycle, cleanup behavior, rejected file types, and device prerequisites. It still leaves some parameter-level detail, especially metadata structure and filePath semantics, to the schema.

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

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

The schema has only 60% description coverage, but the description adds meaning by specifying that metadata must use Device/UploadLocalAsset semantics and that uploads are one multipart file per call. It does not fully explain the required filePath or the metadata object's internal fields, so some semantic gaps remain.

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 starts with a specific verb/resource pair: "AstroToo-only POST /upload_local_asset with one multipart file." It clearly distinguishes this upload path from create/patch binding, the product photo/pixel upload route, and TimesFrame generic upload, so an agent can identify its exact purpose among siblings.

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 states serial one-file-per-call uploads, the required Device/UploadLocalAsset metadata, and that each upload must be bound by a successful create or patch. It also names alternatives and exclusions, including blocked TimesFrame generic upload and the separate product photo route.

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