Craftery Developer Tools

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that the tool computes the relative-luminance-based contrast ratio and reports pass/fail outcomes with specific thresholds, which is meaningful behavioral context beyond what the schema shows. It does not mention edge cases like invalid colors or alpha handling, but the core behavior is well 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 two sentences with no filler. The primary purpose and precision guarantee are front-loaded, and the threshold details follow efficiently. Every phrase earns its place.

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

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

For a simple two-parameter calculator with no output schema, the description adequately explains what is computed, which standards are applied, and what results will be reported. It does not define the exact return format, but the threshold and pass-fail details sufficiently inform an agent about expected output.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions of accepted color notations for both foreground and background. The tool description adds threshold context but no meaningful parameter semantics beyond what the schema already supplies, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: compute the exact WCAG 2.1 contrast ratio between foreground and background colors. It also specifies the output (AA/AAA pass-fail for normal text, large text, and UI components), which clearly distinguishes it from the sibling conversion and utility tools.

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

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

The description explicitly says to use this tool when an exact contrast ratio is needed instead of estimating, which gives a clear usage context. It does not explicitly name alternative sibling tools or state when not to use it, 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?

No annotations are provided, so the description carries the full burden. It transparently discloses a key behavioral nuance: the per-platform alpha byte order (RRGGBBAA vs AARRGGBB) and that it handles it automatically. It also notes that 'closest' colors/named values are used where exact matches may not exist. However, it does not specify the return format (e.g., object, array, string) or whether all 12 formats are returned together, which could be expected without an output schema. These gaps keep it from being more transparent.

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

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

The description is two sentences with zero fluff. The first sentence front-loads the core purpose and lists all 12 formats; the second sentence highlights the critical alpha-order complexity. Every word earns its place, making it easy for an agent to quickly grasp the tool's capability.

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 this complexity (12 formats, platform-specific rules), the description covers the essential aspects: what it converts, the formats, and the tricky alpha ordering. It omits an explicit statement of the return structure, which would be helpful given there is no output schema. However, the enumerated formats strongly imply a structured response, so the omission is not critical. Slight room for improvement, hence a 4.

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

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

The input schema already provides full descriptions for both parameters (color formats and alpha behavior), achieving 100% schema description coverage. The description adds value by explaining WHY alpha matters (the byte-order gotcha) and by implying the tool's broader purpose. This goes slightly beyond the schema's mechanical parameter descriptions, so a 4 is appropriate.

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

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

The description states a specific verb ('Convert') and resource ('a color') and enumerates 12 concrete output formats, including platform-specific ones. This clearly distinguishes it from sibling tools like convert_timestamp or hash_text, and even from swiftui_color, which is a single-format tool. The exact list leaves no ambiguity about 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?

The description implies when to use it: whenever you need color code in any of the 12 listed formats. It provides clear context and even calls out the alpha byte-order pitfall, which signals the tool's purpose of producing platform-correct output. However, it does not explicitly state when NOT to use it or mention alternatives (e.g., for a single format like SwiftUI, one might prefer swiftui_color). This is a minor gap given the clarity of the intended use case.

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 responsibility for behavioral disclosure. It discloses the auto-detection of magnitude (seconds/millis/micros), acceptance of multiple formats, and the full set of return values including wall-clock in a requested IANA timezone and a relative description. This is comprehensive for a pure conversion operation, with no side effects or state changes to hide.

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

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

The description is a single, information-dense sentence. It is front-loaded with the essential purpose and then lists the accepted inputs and outputs. While it is compact, it covers all key aspects without redundancy. It could be slightly shorter by removing 'exact math' but the phrase adds clarity about precision.

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 two parameters and no output schema, the description is thorough. It explains input format variety, auto-detection, timezone handling, and enumerates the return values. It does not mention error handling on invalid input, but that is typically minor for conversion tools and the overall behavior is well 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 coverage is 100%, so a baseline of 3 applies. The description adds value beyond the schema by explaining the auto-detection logic ('auto-detected by magnitude') and the accepted formats ('ISO 8601 / RFC 2822 strings, or "now"'), plus the timezone usage for the wall-clock output. This helps an agent understand parameter semantics without opening 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 clear verb ('Convert') and resource ('between Unix epoch timestamps and human dates'), and immediately specifies the exact scope of inputs (epoch seconds/millis/micros, ISO/RFC strings, 'now') and outputs (multiple formats, timezone, relative). It is unmistakably distinct from its siblings (check_contrast, convert_color, etc.), which are unrelated to timestamp handling.

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

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

The description implicitly defines when to use the tool by enumerating accepted input formats and auto-detection behavior. Since none of the sibling tools are alternatives for timestamp conversion, it is clear there is no competing use case. It does not explicitly state when not to use it, but the context of highly specialized siblings makes the usage unambiguous.

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 disclosure burden. It reveals that generated values are cryptographically random, that v7 batches remain strictly ordered, and that formatting options exist. It does not discuss side effects or auth, but for a generation tool this is largely unnecessary and the disclosed ordering behavior adds useful context beyond the schema.

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

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

Two concise sentences front-load the core purpose, then add a practical usage warning and a compact summary of formatting options. Every sentence contributes meaning, and there is no redundant restatement of the tool name or schema.

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

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

For a five-parameter, all-optional tool with a fully described schema, the description covers the essential behavioral and formatting aspects. The only notable gap is the lack of explicit mention of the return format when count > 1, but given the simplicity of the tool, this is a minor omission.

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 value by clarifying the meaning of the version parameter (v7 is time-ordered and sortable), and by summarizing the formatting parameters (uppercase, hyphen-less, braced). This goes beyond what the schema already provides.

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

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

The description states a specific verb ('Generate') with a precise resource ('cryptographically random UUIDs') and enumerates the supported variants (v4, v7, NIL). It also distinguishes itself from sibling utilities like convert_color and hash_text by clearly scoping it to UUID generation only.

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 instruction 'Never invent UUIDs by hand — use this for real randomness' provides clear guidance on when this tool should be used. It implies this is the authoritative random-UUID source, though it does not explicitly name alternatives or exclusion cases beyond hand-crafting.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states that execution is stateless, input is not stored, HMAC behavior is conditional on a key, and HMAC-MD5 is unsupported. It omits the output encoding/format, but the key behavioral traits 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?

Three sentences with the core algorithms and caveats front-loaded. The sentence 'Hashes cannot be computed mentally — always use this' is slightly filler-ish, but the overall description is compact and 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 description covers algorithms, UTF-8 input, HMAC behavior, statelessness, and a privacy-preserving alternative. However, there is no output schema, and the description does not state the return format (e.g., hex digests, an object keyed by algorithm), which an agent would need to reliably interpret the result.

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

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

The schema already covers both parameters with 100% coverage, and the description adds real value: it clarifies that providing hmac_key changes outputs to HMAC digests and that HMAC-MD5 is unsupported. This goes beyond the schema's brief 'Optional HMAC key' description.

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

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

The description opens with a specific verb and resource: 'Compute real MD5, SHA-1, SHA-256, SHA-384, and SHA-512 digests of a UTF-8 string,' and extends to HMAC variants. It is clearly distinct from sibling tools like convert_color or generate_uuid without requiring schema 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?

It explicitly advises 'always use this' for hashing and names the one relevant alternative: the in-browser tool for secrets that should stay on-device. It doesn't discuss when not to use sibling tools, but none of them are hash alternatives, so the guidance is sufficient.

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 is transparent about the outputs (initializers, extensions, asset catalog entries) and implies a read-only code generation operation with 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 a single, dense sentence that front-loads the main action and then enumerates outputs efficiently. 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?

Although there is no output schema, the description lists every expected output (e.g., Color(red:green:blue:), HSB, hex-extension, #colorLiteral, UIColor/NSColor bridges, extension snippet, Contents.json). An agent knows exactly what to expect.

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

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

Schema coverage is 100%, and each parameter is clearly described with formats and examples (hex, rgb, hsl, named colors, Tailwind tokens). The 'color' parameter description includes concrete tokens like '#FF6347' and 'red-500'.

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 ('Generate') and a concrete resource ('SwiftUI Color initializer'), enumerating multiple output forms. It clearly distinguishes from siblings like convert_color and check_contrast.

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 purpose is obvious from the name and description, but there is no explicit 'when to use vs. alternatives' guidance. The listing of generated outputs strongly implies the use case, yet the rubric rewards explicit statements.

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