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

With no annotations, the description carries the burden of disclosing behavior. It accurately describes that this is a read-only introspection tool that reports environment capabilities and server version, and gives specific conditions for each tier. No side effects or hidden behavior are implied.

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, front-loaded with the main purpose, and uses structured bullets-like sentences to explain each tier. Every sentence adds value with no redundancy.

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

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

The tool is simple (no params, no side effects) and has an output schema, so return values need not be detailed. The description fully covers the tool's purpose, tier logic, and version reporting. Nothing important is missing.

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

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

There are zero parameters, so the baseline is 4. The description adds sufficient context about what the tool inspects, making the lack of parameters clear and expected.

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

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

The description clearly states it reports available capability tiers, with specific detail on each tier's conditions. This distinguishes it from all sibling tools, which are operational (emu, store, build, etc.).

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

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

It explains the prerequisites for each tier (e.g., tier2 requires Pillow, tier4 requires token), giving clear context on when and how to interpret results. It doesn't explicitly list alternatives, but no alternatives exist for capability checking.

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 reveals key behavioral aspects: it returns multiple representations (name, hex, C constant, packed byte, sunlight-corrected hex, sRGB distance) and optionally reports contrast ratio. It does not discuss error handling, but for a pure lookup tool this is a minor omission.

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

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

The description is compact and well-organized: a one-line purpose, an Args explanation, and a Returns list. Every sentence adds useful information without redundancy.

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

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

For a simple two-parameter read-only tool with an output schema, the description fully covers input formats, optional behavior, and output values. No significant gaps remain.

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 has zero descriptions, so the description fully compensates by detailing the accepted color formats (hex with/or without hash, shorthand, or r,g,b triple) and explaining the background parameter for contrast/legibility reporting. This is richer than the bare 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 opening sentence clearly states the tool maps an arbitrary color to the nearest of 64 Pebble GColors. It uses a specific verb/resource combination and distinguishes itself from sibling tools by its focused palette conversion purpose.

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

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

The description implies usage for when you need to find a Pebble GColor nearest to an arbitrary color, but it does not explicitly mention when not to use it or offer alternatives among sibling tools. Lacks explicit exclusions.

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

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

With no annotations, the description takes on full responsibility for behavioral disclosure. It openly states this is a heuristic, not a human designer, explains it reasons only about color statistics and not glyphs, and advises visual confirmation for hero-value hierarchy. It also discloses the need for the pebble CLI in emulator mode and describes the output as a JSON critique plus image.

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 well-structured and front-loaded with the primary purpose. It uses separate paragraphs for parameters, limitations, and return values without fluff. Every sentence contributes to the agent's ability to invoke the tool correctly, making the length justified.

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 input types, parameter semantics, return value contents, and limitations, which is strong given no annotations and no output schema. It does not detail the exact JSON structure or error behavior, but for selection and invocation purposes it is sufficiently complete to guide an agent.

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

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

Schema description coverage is 0%, but the description fully explains both parameters. It details the accepted formats for `source` (filesystem path, base64, data URI, or 'emulator') and the meaning of `regions` (N×N contrast grid, default 3), adding crucial context beyond the bare 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+resource phrase: 'Critique a Pebble screenshot against the design system.' It clearly states the tool's function and differentiates it from siblings like color_nearest or image_quantize by focusing on holistic design system compliance.

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

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

The description gives clear context for when to use the tool (analyzing screenshots for design adherence) and even includes a cross-reference to capabilities() for emulator capture requirements. However, it does not explicitly mention when not to use it or name alternative tools for simpler tasks, so it lacks full exclusion 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. It discloses validation of button/action names and the specific semantics of each action, but it does not state side effects or whether this mutates emulator state (though implied).

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

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

The description is compact and well-organized, with the main purpose in the first sentence and parameter details following in a clear, structured manner. No redundant information.

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

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

For a tool with simple parameters and the provided descriptions, this is complete. It covers all parameter semantics, preconditions ('running emulator'), and validation behavior. The presence of an output schema means return values need not be described.

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 provides no descriptions (0% coverage), so the description fully compensates. It explains all valid values for 'action', the allowed 'button' choices, the requirement and constraints for 'duration_ms', and that 'tap' requires neither.

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

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

The description uses a specific verb ('Send') and identifies the resource ('the running emulator'). It clearly distinguishes from sibling tools like emu_screenshot and emu_logs by focusing on input injection.

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

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

No guidance is provided for when to use emu_input versus alternatives such as emu_screenshot or emu_start. The description explains internal action modes (press/longpress/tap) but does not compare with other tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the bounded streaming, optional early cut on pattern match, and clamping to max_bytes, including the resulting 'matched' and 'truncated' flags. It does not cover error scenarios or return format, but the output schema likely handles that.

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 opening line is a concise summary, and the second paragraph provides detailed parameter behavior in just two sentences. Every word earns its place, with no filler or repetition.

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

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

For a log retrieval tool, the description covers the core behavior and parameters succinctly. The presence of an output schema shifts the burden of return-value documentation, so the description is sufficiently complete, though it omits details like log ordering or what happens if the pattern is never found.

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

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

The input schema has 0% description coverage, so the description fully compensates by explaining each parameter: 'seconds' limits duration, 'until_pattern' triggers early termination, and 'max_bytes' clamps the result size. This adds significant meaning beyond the bare schema.

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

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

The description clearly states 'Capture emulator logs' and immediately adds the key qualifier 'bounded — never a firehose,' which distinguishes it from other emulator tools like emu_screenshot or emu_input. It is specific about the resource and the action.

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

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

No explicit when-to-use guidance or alternatives are mentioned. While the description implies its use for collecting logs, it does not explain when to choose this over other logging approaches or any exclusions.

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

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

No annotations are provided, so the description carries the burden. It discloses the optional name behavior, .png appending, and the failure modes for a missing or wedged emulator. It doesn't describe the return format or where the image is saved, but the core behavior is transparent.

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

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

Two sentences, front-loaded with the main purpose, then optional parameter behavior, then error cases. Every sentence earns its place with no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers the essential aspects: what it does, how the parameter works, and when it fails. This is complete for an agent to select and invoke the tool.

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

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

The schema only says 'name' is a string or null with a default of null (0% coverage). The description adds substantial meaning: 'Optional name sets the file basename (.png appended if absent),' explaining the purpose and default behavior of the sole parameter.

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

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

The description uses the specific verb 'Capture' with a clear resource: 'one screenshot of the running emery emulator as an image.' This distinguishes it from sibling tools like emu_start, emu_input, emu_logs, and emu_stop, which handle lifecycle, input, or logs.

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

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

The description implies a prerequisite: an emulator must be running. It also states it errors clearly if no emulator is running or it's wedged. This gives clear context for when to use the tool, though it doesn't explicitly name alternatives or exclusions.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It adds valuable context: the operation is idempotent-ish (will reconnect/restart if running) and requires the pebble CLI. This goes beyond a basic 'what it does' statement, though it omits details like boot time 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?

The description is highly concise, using three short sentences to convey the core action, idempotency, and a prerequisite. Every sentence earns its place, and the main verb 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?

Given the tool's simplicity (one optional parameter, output schema present), the description is mostly complete with the action, default, idempotency, and requirement. It could enumerate platform choices, but the output schema covers return values, so the gap is not critical.

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

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

The input schema has 0% description coverage, and the description only mentions 'given platform (default emery)' without explaining valid platform values or any semantics. It adds the default value but does not help the agent understand what to pass for 'platform'.

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

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

The description clearly states the tool boots the Pebble emulator, names the resource and action, and distinguishes it from siblings like emu_stop, emu_screenshot, and pebble_build. It also notes the default platform, providing a specific scope.

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 context by mentioning idempotent behavior and a prerequisite (pebble CLI on PATH), which helps the agent understand execution conditions. However, it does not explicitly mention when to use this tool versus alternatives or exclude any cases, so guidance is implied rather than explicit.

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

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

No annotations are present, so the description carries the full burden. It discloses the main effect (shutdown), the wipe behavior (clears storage), and the CLI requirement. It could add what happens with unsaved state or error conditions, but for a simple stop tool this is adequate.

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

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

Two sentences, no filler, front-loaded with the core action. Every sentence serves a purpose: the first states the primary function, the second explains the wipe option and the prerequisite.

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

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

For a one-parameter stop tool, the description is complete: it covers the action, the optional flag, and the external dependency. It does not specify what happens if no emulator is running, but that is a minor gap given the simple scope.

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

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

The schema has only one boolean parameter, 'wipe', with zero coverage in the schema descriptions. The description fully explains the parameter: 'wipe=True also clears its storage' and adds why it matters (fixes flakiness). This compensates entirely for the low schema coverage.

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

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

The description uses a specific verb+resource: 'Shut down the running emulator', immediately clarifying the tool's function. It also mentions the wipe option, which distinguishes it from sibling tools like emu_start and emu_screenshot.

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

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

Provides clear usage context: 'Wiping is the fix for most emulator flakiness' explains when to enable wipe. It also notes the prerequisite of the pebble CLI. However, it does not explicitly contrast with alternatives like emu_start or mention when not to use it.

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

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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It covers installation discipline (kill+wipe-first), environment variable override, default tempdir, the 40-shot guard, the metadata return format, and an extensive live-write hazard warning. This is far beyond a typical tool description.

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 long but each paragraph carries distinct information: what it does, how it executes, what it returns, its guard, and its safety rules. It's structured with paragraph breaks and front-loaded with the main purpose, so the length is justified.

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

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

The tool is complex (executes flows, installs apps, captures screenshots, has safety hazards), and the description addresses all major aspects: input format reference, output structure, execution behavior, limits, and safety. Given no output schema, the description conveys the return shape. It is complete for an agent to use effectively.

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

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

Both parameters are described beyond the schema: flow_text is identified as a flow spec with a reference to the line format, and out_dir is explained as defaulting to a fresh tempdir. While the exact flow_text syntax is externalized to a reference, the description gives enough context for an agent to understand what to pass.

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+object and output: 'Run a gallery-style flow spec against the emery emulator and return every screenshot.' This clearly distinguishes it from sibling tools like flow_validate (validation) and emu_input (individual button presses).

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

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

The description provides clear context for when to use the tool (running a flow and capturing screenshots) and includes safety exclusions about never confirming live-write actions. However, it doesn't explicitly name alternatives or contrast with flow_validate/emu_screenshot, so it falls short of the strictest 'when vs when-not' standard.

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 discloses that it does not execute the flow, returns a summary (step_count, shot_count, steps_by_type, cap check), reports parse errors with 1-based line numbers, and requires no emulator. This is substantial behavioral context, though it omits permission/side-effect statements.

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 ('Parse a flow spec WITHOUT running it — a cheap pre-check'), followed by return details and usage guidance. All sentences are relevant, but the second sentence is slightly long and could be tightened.

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

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

The tool is simple (one parameter) and the description covers purpose, behavior, return summary, error handling, and usage context. An output schema exists, so return values need not be detailed. It is complete for a validation tool, though it could mention edge cases or implicit limitations.

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 one parameter (flow_text) with no description, and the description only refers to it as 'flow spec.' It does not explain the format or syntax of the flow spec, so the description adds minimal meaning beyond the parameter name. Since schema coverage is 0%, it partially compensates but not fully.

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

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

The description clearly states the tool parses a flow spec without running it, explicitly distinguishes it from flow_run (the sibling execution tool), and describes the resulting step summary and error behavior. This is a specific verb+resource with strong sibling differentiation.

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

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

The description says 'Needs no emulator, so it is the right tool to validate a flow before spending an emulator run,' which clearly indicates when to use it (before executing a flow) and implies the alternative is running the flow. It does not explicitly state when not to use it or name alternatives by tool name, so it falls short of a 5.

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

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

With no annotations, the description carries the full transparency burden and does so thoroughly. It discloses that the tool is a 'pure lookup' with 'no resource cost,' never touches the network or toolchain, and does not silently recommend fonts when glyphs are missing—instead flagging 'fits: false' and 'missing_glyphs'. It also explains the optional sorting/filtering effects of size_hint and style.

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 longer than average, but every sentence adds value—detailing input modes, output contents, parameter effects, and availability. It is well-structured with clear paragraphs and example code-like strings, and despite length, there is no filler or redundancy.

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

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

Given no annotations, no output schema, and 0% schema description coverage, the description is remarkably complete. It covers purpose, both invocation paths, response elements (ordered FONT_KEY_* list, minimal_character_regex), parameter semantics, and operational constraints. An agent can confidently select and invoke this tool based solely on the description.

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

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

Schema coverage is 0%, but the description fully compensates. It explains role_or_text with concrete examples and directs the check behavior, defines size_hint as 'sorts candidates by closeness to that size,' and defines style as 'filters/prefers a weight substring, e.g. bold.' All three parameters receive meaningful semantics beyond their bare titles.

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: 'Recommend Pebble system fonts for a UI role or a literal string.' It clearly distinguishes two usage modes (role vs. literal text) and even lists example roles, leaving no ambiguity about the tool's function. No sibling tool handles fonts, so differentiation is inherent.

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

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

The description gives explicit guidance on when to pass a role ('Pass a role like...') versus literal text ('Pass literal text instead...'), including expected outcomes for each. It also notes the tool is 'always available regardless of capability tier,' which is a useful when-to-use signal. It does not explicitly name alternatives, but none relevant exist among siblings.

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 well: it discloses input formats, fit modes, dither options, a corrected-display flag, and the exact return shape including a preview upscale behavior. It does not mention error conditions or side effects, but for a non-destructive image processing tool this is adequate.

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

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

The description is well-structured with an executive summary followed by a bullet-style args list and a one-sentence return description. Every line adds information; there is no filler or repetition of schema defaults.

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

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

Despite having no annotations and no output schema, the description covers all five parameters, their options, and the return value in enough detail for an agent to invoke the tool correctly. It also notes an edge case (2× upscaling for small images), making it complete for the tool's complexity.

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

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

Schema coverage is 0%, but the description compensates fully by explaining each parameter: source accepts path/base64/data URI, target includes named dimensions, fit explains contain vs cover, dither lists all allowed values, and corrected is described as sunlight-display preview. This is exactly the meaning the schema lacks.

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, multi-verb purpose: 'Resize/letterbox an image to a named target, quantize, and preview it.' This distinguishes it from sibling tools like image_quantize by including resize, letterbox, target dimensions, and preview output.

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

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

The description clearly implies usage for image preparation to named targets, but it does not explicitly state when to use this tool versus alternatives such as image_quantize or color_nearest. There are no exclusions or alternative recommendations, so guidance is only implied.

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

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

No annotations are provided, but the description discloses key behaviors: it returns a stats object and preview image, details dithering options, explains the 'corrected' parameter's effect on preview while noting reporting is unaffected, and mentions 2× upscaling for small images. This gives the agent a clear picture of what will happen.

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

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

The description is a compact docstring with explicit Args and Returns sections. It front-loads the main purpose in the first sentence and uses no filler. Every sentence adds value, from parameter semantics to return details.

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

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

With no output schema and no annotations, the description must convey all relevant context. It covers inputs, outputs, defaults, and edge-case behavior (upscale, corrected preview). It does not mention error conditions, but for this tool's complexity, the description is sufficiently complete for an agent to invoke it correctly.

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

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

The input schema only provides types and defaults. The description compensates fully by explaining each parameter: 'source' accepts a filesystem path, base64, or data URI; 'dither' lists three options with default; 'corrected' explains sunlight-corrected preview behavior. This adds significant meaning over the bare 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: 'Quantize an image to the Pebble 64-color palette; return stats + preview.' This clearly distinguishes from sibling tools like color_nearest or image_prep by specifying the exact palette and output.

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

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

The description provides clear context for use: quantization of an image to a specific palette, with an input-format note for hosts without filesystems. However, it does not explicitly name alternative tools or exclusionary conditions, so it falls short of the highest bar.

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 responsibility for disclosure. It adds meaningful context by specifying that labels default to palette names, and it limits the color count to 1..64. However, it does not mention side effects like file output or error handling, which would be expected for a tool that generates a PNG.

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 a one-sentence summary, followed by a clean Args section. Every sentence contributes necessary information, and it is appropriately sized for a two-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 tool's purpose, parameters, and defaults, which is sufficient for a simple rendering tool. It doesn't specify how the PNG is delivered (e.g., file path or base64) or the exact grid layout, but these are secondary details. Given the output schema is absent, the description is mostly complete but could add one line about the output channel.

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 provides no parameter descriptions, so the description fully compensates. It explains that colors accept hex strings or "r,g,b" triples with a count constraint, and it clarifies that labels are optional with a default behavior. This is exactly the kind of semantic enrichment needed.

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

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

The description clearly states a specific verb and resource: "Render a labeled grid of color swatches to a PNG for eyeballing." This distinguishes the tool from siblings like color_nearest or image_quantize by emphasizing visualization for human inspection.

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

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

The phrase "for eyeballing" provides a clear context for when the tool is appropriate, but there is no explicit mention of alternatives or when not to use it. It lacks the explicit exclusions that would earn a 5, but the use case is well implied.

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

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

With no annotations, the description fully discloses behavior: it validates known constraints before conversion, returns structured violations instead of a broken file, reports non-fatal warnings (odd coordinates), and on failure lists exactly what to fix. It also states the tool 'never guesses at a lossy conversion,' setting explicit expectations about failure handling.

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 well-organized, with clear sections: purpose, validation behavior, supported/unsupported features, success/failure output, and next-step advice. Every sentence adds value, and the structure allows an agent to quickly extract the important constraints and response contract.

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

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

Given the tool's complexity (format conversion with many constraints), the lack of an output schema, and zero annotations, the description is remarkably complete. It covers input requirements, failure modes, success output fields, warnings, and remediation steps. An agent has enough context to decide when to invoke this tool and what to do with the result.

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

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

The schema has only one parameter, svg_text, with no description (0% coverage). The description compensates by explaining what the SVG input should contain—supported element types, unsupported transforms, and required pre-processing (flatten curves). It implicitly defines svg_text as the SVG XML string and provides concrete guidance on its valid content, though it does not explicitly say 'svg_text is the SVG source code.'

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

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

The description opens with a specific verb+resource: 'Convert an SVG icon/vector to a Pebble Draw Command (.pdc) file.' This clearly distinguishes the tool from siblings like image_quantize or font_plan, which address different steps in the Pebble design pipeline.

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

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

The description gives abundant context on appropriate use: it enumerates supported SVG elements, lists unsupported features (gradients, masks, clip paths, etc.), and instructs the user to 'flatten curves first' and remove unsupported elements before retrying. It stops short of explicitly naming alternative tools or saying 'use this tool instead of X', but the constraints provide clear when-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 full transparency burden. It discloses that the tool executes an external command, what the return value includes (success, .pbw path, diagnostics), and a prerequisite. It does not mention side effects like writing build artifacts to disk, but for a build tool the main behavior is clear.

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

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

The description is three sentences, front-loaded with the purpose, and each sentence adds distinct value: what it does, how it runs, and what it returns plus a prerequisite. No filler or redundancy.

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

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

For a build tool with an output schema, the description covers the essential context: command executed, path semantics, required CLI, and the nature of the returned data. The presence of an output schema means return values don't need to be spelled out in detail. This is complete for an agent to decide whether and how to invoke it.

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

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

Schema coverage is 0%, so the description must add meaning. It explains that project_dir can be absolute or relative to the workspace root, which is exactly the semantic detail beyond the raw schema. For a single parameter, this is sufficient and useful.

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

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

The description clearly states 'Build a Pebble app project' with a specific verb and resource, and distinguishes from sibling tools like project_new, pebble_install, and flow_run by focusing on compiling and returning diagnostics. It immediately conveys the tool's core function.

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 specifies the action (runs pebble build), the project_dir parameter's path resolution, and the requirement for the pebble CLI on PATH, with a pointer to capabilities(). This gives clear context for when to use it, though it doesn't explicitly mention when not to use it or name alternatives.

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

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

With no annotations provided, the description carries the transparency burden. It explicitly discloses destructive behavior ('emulator is killed and wiped first'), startup delay, and environmental prerequisite ('Requires the pebble CLI on PATH'). This is substantial disclosure.

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

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

The description is four concise sentences, front-loaded with the primary action, then target semantics, side effects, and environment requirement. Every sentence adds value with no redundancy.

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

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

The description covers target types, destructive side effects, startup delay, and the CLI requirement. It omits the 'platform' parameter meaning, and since an output schema exists, return values are not required. Overall it is adequate for a tool with this complexity.

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

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

The description thoroughly explains the 'target' parameter (project directory vs .pbw, relative path resolution). However, it does not mention the 'platform' parameter at all, leaving its default and meaning undocumented. Since schema description coverage is 0%, this is a partial gap in compensating for parameter 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?

The description uses a specific verb and resource: 'Install an app into the emulator, starting it if needed.' This clearly differentiates it from sibling tools like emu_start (which just starts the emulator) and pebble_build (which builds without installing).

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 context: target can be a project directory or a .pbw file, relative paths resolve against workspace root. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusions.

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

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

With no annotations, the description carries full burden. It discloses key behaviors: copying source, creating directories if missing, appending/updating the media entry, supporting base64/data URIs for bitmaps, routing through the design tier when prep_target is set, and returning the updated media list and written file. This is thorough and transparent.

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

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

The description is efficiently structured, front-loading the primary purpose in the first sentence. Subsequent sentences add necessary detail about copying, registration, and edge cases. It's slightly long but every sentence contributes valuable information, so it's appropriately concise.

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 5 parameters, no annotations, and no output schema, the description is complete. It explains the action, all parameters, behavioral nuances, and return values (updated media list and written file). There are no obvious gaps in understanding what the tool does.

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

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

Schema description coverage is 0%, so the description must compensate. It explains resource_type values ('bitmap' | 'font' | 'raw'), defines prep_target with examples ('emery', 'menu-icon'), clarifies that source can be base64/data URI for bitmaps, and meaningful context for dir and name. This fully compensates for the lack of schema 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?

The description clearly states the tool's action with a specific verb and resource: 'Add a resource to a project and register it in package.json.' It further details that it copies source into resources/ and updates the media list, distinguishing it from sibling tools like image_prep or project_set_meta.

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

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

The description provides clear context: you use this tool to add resources to a project, and it explains optional preprocessing via prep_target. It does not explicitly mention alternatives or when-not-to-use, but the behavior is clear enough for an agent to infer appropriate usage.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explicitly states error behavior ('Raises a clear error if dir has no package.json or no pebble block') and describes the inference logic (language detection from projectType and src/ layout). It does not explicitly state read-only, but the verb 'Summarize' strongly implies no 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?

The description is front-loaded with the main purpose, then lists return fields in a structured, comma-separated format, and ends with error conditions. Every sentence earns its place without unnecessary fluff. The formatting makes it easy to scan.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is fairly complete: it enumerates the full return payload and clearly states error conditions. It does not mention side effects, but 'Summarize' implicitly indicates a read-only operation. Missing explicit read-only confirmation is a minor 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 0% for the single parameter 'dir'. The description only indirectly clarifies that 'dir' is a directory containing package.json (from the error condition). It does not explicitly define the expected path format or that it should point to the project root. This is a partial compensation but not fully explicit.

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

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

The description opens with a specific verb-resource statement: 'Summarize an existing Pebble project from its package.json.' It also enumerates the exact return fields (name, displayName, uuid, etc.), making the tool's scope unmistakable and distinguishing it from siblings like project_set_meta or project_new.

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 context is clear: this tool is for reading/summarizing an existing Pebble project. It does not explicitly mention alternatives or when-not-to-use, but the phrasing 'existing' and the focus on package.json makes its role distinct. A brief exclusion (e.g., 'to create a project use project_new') would elevate it to a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It details side effects (writes files directly), file structure per language, platform defaults and clamping, dropped platforms reported in warnings, and the returned fields (path, uuid, etc.). This is highly transparent.

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

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

The description is long but appropriately so given 7 parameters and no schema descriptions. It is well-structured with bolded parameter names and code-formatted paths. Every sentence adds valuable information, and the key purpose is front-loaded. No fluff.

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, so the description must explain return values, which it does clearly. It also covers file creation, platform constraints, and implications of options. It is complete for a scaffolding tool of this complexity.

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

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

The schema has 0% description coverage, so the description must explain all parameters. It thoroughly explains every parameter: kind (watchface/watchapp), language (c vs javascript with details), platforms (defaults and clamping), companion, config, and dest_dir. Even name is referenced in the path and file naming (`<slug(name)>`). This fully compensates for the schema 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?

The first sentence states a specific verb ('Scaffold') and resource ('new, immediately buildable Pebble project'), clearly distinguishing it from siblings like pebble_build (build) and project_info (inspect). The additional detail about writing files directly without shelling out to the CLI adds further specificity.

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

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

The description provides clear context for when to use this tool: for scaffolding a new project on hosts without the CLI. It explains platform clamping for JavaScript projects and the effect of companion/config options. However, it does not explicitly mention when NOT to use it or alternative tools (e.g., use pebble_build for compilation).

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 well: it discloses in-place editing, validation against seven known platforms, canonical ordering, and that capabilities/message_keys are replaced wholesale. It also notes the return value. Missing details like error behavior or prerequisites, but overall strong.

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, front-loaded with the core action, and each sentence adds meaningful detail about parameter behavior. No fluff or repetition.

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

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

Given the 6 parameters and no output schema or annotations, the description covers the key behaviors: what each parameter does, validation, and return value. It omits prerequisites (e.g., valid project directory) and error handling, but for a focused mutation tool it is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the semantics of uuid (including the 'new' literal), add/remove_platforms (validation and canonical order), and capabilities/message_keys (wholesale replacement). The required 'dir' parameter is not explicitly described, but the name is somewhat self-explanatory.

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

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

The description clearly states the tool edits a project's 'pebble' metadata block, using a specific verb ('Edit') and a specific resource. It distinguishes from sibling tools like project_info (read) and project_new (create) by focusing on modification of an existing metadata block.

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

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

The description implies use for editing existing project metadata, but does not explicitly state when to use this tool over alternatives or provide exclusions. It lacks direct guidance on when not to use it, though the context is reasonably clear from the parameter descriptions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the build-then-install-then-screenshot flow, including the destructive 'kill+wipe-first' emulator reset, the failure path (built=false, skips install), and the exact return fields. It even notes the CLI dependency, giving the agent a clear picture of side effects and requirements.

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 moderately sized but efficiently structured: a punchy first sentence summarizing the tool, followed by behavior, return value, failure mode, and prerequisite in logical order. Every sentence contributes information, though it could be tightened slightly without losing meaning.

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

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

Even without an output schema, the description lists the return fields and explains failure behavior, making it quite complete for a composite tool. It lacks details on the 'platform' parameter and what happens if installation fails, but these are minor gaps relative to the overall richness of information provided.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'dir' well (relative to workspace root or absolute), but it says nothing about 'platform' (default 'emery'), leaving the agent without guidance on this parameter. The description adds some value by clarifying the main parameter, but it does not fully cover the schema's parameters.

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

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

The description opens with 'Build, install, and screenshot a project — the one-call "does it run?"', which clearly states the tool's verb, resource, and overarching purpose. It distinguishes itself from sibling tools like pebble_build, pebble_install, and emu_screenshot by advertising this as a combined smoke-test operation.

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

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

The description explicitly frames this as 'the fastest "did my change compile" check', giving a clear use case. It also implies when not to use it (e.g., for a full build-only workflow) by describing its combined behavior, though it does not explicitly name alternative tools. The prerequisite 'Requires the `pebble` CLI on PATH' provides additional contextual 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 provided, the description must disclose behavioral traits. It lists the return fields in detail (hearts, author, platforms, release, download URL, images), indicating a read-only metadata operation. However, it does not mention potential errors, authorization requirements, or any side effects beyond the obvious read-only nature.

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

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

The description is two sentences, front-loaded with the core purpose, followed by a concise list of returned data. Every sentence adds value, with no filler or redundancy.

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

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

Given a single required parameter, an existing output schema, and a simple return structure, the description covers the primary invocation and the key data points. It could mention where the app_id comes from or what happens for invalid IDs, but it is generally complete for a metadata lookup tool.

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

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

Schema coverage is 0%, so the description must add meaning to the single parameter app_id. It says 'by its id' but does not provide any format, example, or where to obtain the ID. This is minimal compensation for the schema's lack of documentation.

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 'Full metadata for one appstore app or watchface by its id', a specific verb+resource that clearly distinguishes this tool from siblings like store_search or store_developer. It explicitly states the single-item lookup by ID, making the purpose unambiguous.

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

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

The description implies when to use it (when you have a specific app id) but does not explicitly contrast it with alternatives or list exclusions. The sibling tool names (store_search, store_collection, etc.) further clarify the context, but an explicit 'use this instead of...' would strengthen this dimension.

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 burden. It discloses pagination via has_more, the compact summary fields, and the hardware-dependent compatible flag. It does not mention read-only status or error behavior, but 'List' and these output details provide adequate transparency.

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

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

Single sentence, front-loaded with the core action, and includes useful examples and pagination/flag notes without redundancy.

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

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

With an output schema present for return values, the description covers purpose, category examples, hardware behavior, and pagination. The main remaining gap is the undocumented sort parameter and lack of explicit sibling differentiation, but overall this is sufficient for a simple list tool.

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

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

Schema description coverage is 0%, and the description only clarifies category_slug (via examples) and hardware (via the compatible flag). It does not explain sort, limit, or offset beyond the broad 'paginated' mention, nor does it mention defaults such as limit=20 or offset=0.

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

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

Description opens with specific verb and resource ('List apps in a store category') and gives concrete slug examples. This clearly differentiates it from sibling tools like store_search or store_app, which target query-based or single-app scenarios.

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

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

The description clearly implies the use case: browsing a category's app listing with pagination. It does not explicitly name alternatives or when-not-to-use, but the context is unambiguous enough for an agent to select it appropriately.

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

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

With no annotations provided, the description carries the burden of explaining behavior. It discloses pagination behavior (has_more flag, offset/limit paging) and the result format (fields per row), which is useful. However, it does not mention whether any side effects occur, authentication requirements, or error conditions. The description is adequate but not rich.

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 well-structured. It front-loads the purpose in the first sentence, then provides necessary parameter details in the following sentences. No unnecessary filler; every sentence adds value.

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

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

Given the tool has 6 parameters and an output schema, the description covers the essential behavior: pagination, result fields, and required parameter values. However, it leaves out 'sort' semantics and possible hardware values. The output schema likely covers return structure, so the description is mostly complete but has minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for slug (examples), type_string (allowed values), limit/offset (pagination), and hardware (requested hardware flag), but does not explain the 'sort' parameter at all. Partial compensation with notable gaps.

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

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

The description clearly states the tool's function: 'List a named store collection, paginated, as compact summaries.' It specifies the resource (store collection) and provides concrete examples of slug values, which distinguishes it from sibling tools like store_search or store_category.

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

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

The description gives context on how to use the tool (e.g., valid slug examples and type_string values) and explains pagination, but it does not explicitly say when to use this tool over alternatives like store_search or store_developer. The usage is implied rather than contrasted with siblings.

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

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

With no annotations, the description carries the transparency burden and does well: it explains what rows contain and explicitly states the graceful missing-id behavior (returned in missing_ids rather than failing). It doesn't cover authentication or rate limits, but for a read-only bulk fetch the key behaviors are disclosed.

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

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

The description is compact: a one-sentence purpose, a one-sentence breakdown of rows, and a one-sentence error-handling note. The most important information is front-loaded and every sentence adds value.

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

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

Given the tool's modest complexity (one parameter, a comparison-table output), the description fully covers what the agent needs: what ids to pass, what fields to expect, and how missing ids are handled. The output schema could provide further detail on return types, but the description alone is sufficient for correct selection and invocation.

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

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

The only parameter, app_ids, has no schema description (0% coverage), so the description must compensate. It does by explaining the tool fetches 'several apps by id' and that unresolved 'ids' appear in missing_ids, making the parameter's meaning and behavior clear beyond the raw 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 action ('Bulk-fetch several apps by id') and output ('side-by-side comparison table'), which clearly distinguishes it from sibling tools like store_search or store_app. The purpose is immediately understandable and unambiguous.

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

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

The phrase 'for competitive research' gives clear usage context, and the tool's batch-by-id nature implies using it when you have specific app identifiers rather than a search query. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently describes the paginated response, the compact summary fields, the compatible flag tied to hardware, and the has_more indicator. It does not cover edge cases or side effects, but for a read-only listing tool, this is substantial transparency.

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

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

The description is two sentences, front-loaded with the main action, and includes only essential details. Every word earns its place, and the structure is highly scannable.

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 5 parameters, no annotations, but an output schema exists. The description covers the core behavior, output shape, and pagination, but leaves the sort parameter undefined and does not explicitly state how offset/limit interact with pagination. It is adequate but not fully complete for an agent to use all features correctly.

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

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

The description enriches the hardware parameter by explaining its role in the compatible flag, and implies limit/offset through 'paginated' and has_more. However, it fails to explain the 'sort' parameter's options or meaning, and developer_id is only implied, not explicitly tied to the parameter. Given 0% schema coverage, this is a partial but incomplete 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?

The description specifies a clear action ('List'), a precise resource ('every app published by one developer'), and distinguishes itself from sibling tools like store_search and store_collection by focusing on a single developer's catalog. It also mentions pagination and the output format, making the purpose unmistakable.

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

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

The description clearly implies the tool's use case: when you need all apps for a given developer_id, with optional hardware filtering. However, it does not explicitly state when not to use it or offer alternatives, though the context is strong enough for an agent to select it appropriately.

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

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

With no annotations, the description fully discloses side effects: it creates dest_dir, writes the file, sanitizes filenames to prevent traversal, enforces a 32 MiB cap, and sends a User-Agent. Error conditions (no published .pbw, non-directory dest_dir, empty body, oversize body) are enumerated, providing comprehensive behavioral transparency.

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

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

The description is front-loaded with the main action and then adds concise, high-value details about side effects, safety, and return value. Every sentence earns its place; no filler or repetition.

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

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

For a tool with no annotations and a sparse schema, the description is remarkably complete: it covers purpose, side effects, error handling, security behavior, return values, and downstream usage. The existence of an output schema allows it to omit detailed return formatting, but it still mentions key return fields.

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

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

The input schema has 0% coverage, but the description uses both parameters in context: 'app_id' identifies the app and 'dest_dir' is the destination directory that gets created if needed. This provides enough meaning for an agent to understand their roles, though it does not explicitly define acceptable formats or sources for app_id.

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

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

The description opens with a specific verb–resource pair: 'Download an app's latest-release .pbw to dest_dir.' This clearly distinguishes it from sibling tools like store_search or store_app, which likely handle metadata. The purpose is unambiguous.

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

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

The description states that this feeds the install/emulator flow and instructs passing the returned path to a Tier 3 install tool, giving clear usage context. However, it does not explicitly name alternative tools or state when not to use this tool, only implying it via the flow description.

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

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

With no annotations, the description carries the full burden and does exceptionally well. It discloses that it is client-side, fetches a bounded pool, ranks by substring/token matches, returns a score, and has coverage limitations. It even warns that matching is on listing text, not behavior or tags.

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, uses a clear 'Consequences' list for limitations, and ends with a practical alternative pointer. Every sentence adds value; no fluff. It's appropriately structured for a tool with behavioral caveats.

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

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

The tool is complex (client-side search with real constraints), and the description addresses all critical context: algorithm, coverage limits, `type_string` constraints, and alternative tool. Since an output schema exists, return values need no explanation. This is a complete, self-sufficient description.

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

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

Schema coverage is 0%, so the description must add meaning. It explains `query` as the keyword, `type_string` allowed values, and the ranking algorithm. It doesn't explicitly describe `hardware` or `max_results`, but the parameter names and defaults offer some clarity. Overall, it compensates well beyond the bare 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 'Search the store by keyword' — a specific verb and resource. It clearly distinguishes itself from sibling tools by explicitly stating 'For an exact app you already know, prefer ``store_app`` by id.' It also clarifies the client-side approach and limitations.

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

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

The description gives explicit when-to-use guidance: it's the keyword search option, while `store_app` is the exact-id alternative. It also explains when not to rely on it (obscure apps outside the bounded pool) and outlines real limits, so the agent can decide accordingly.

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