Craftery Developer Tools

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond them by disclosing the exact computation method (relative-luminance) and the thresholds it evaluates against (4.5/7, 3/4.5, 3), which tells the agent what the result means.

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?

A single dense sentence with no filler; the core computation is front-loaded and the pass/fail thresholds follow as supporting detail. Every clause carries information.

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

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

With no output schema, the description does a good job explaining what is returned (ratio plus AA/AAA verdicts per text/component category). It stops short of describing output structure or edge cases such as invalid color notation, so it is strong but not fully complete.

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

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

Schema description coverage is 100% and both parameters are fully documented in the schema, including all accepted color notations. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a precise verb (computes) and resource (WCAG 2.1 contrast ratio between foreground and background), and the specificity of naming the exact standard and formula clearly separates it from generic siblings like convert_color.

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

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

Usage is implied by the description (checking accessibility compliance for a color pair), but there is no explicit when-to-use statement, no when-not-to-use, and no routing to alternatives such as convert_color. Adequate but leaves the agent to infer the trigger.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them by disclosing the alpha byte-order convention per platform (RRGGBBAA on web, AARRGGBB on Android/Compose/Flutter), which an agent could not infer. It does not describe the response shape (e.g. keyed object vs list) or invalid-input 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?

Two dense sentences with no filler; the output-format list is front-loaded and the non-obvious alpha-ordering caveat is kept brief. Every clause carries information.

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

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

With no output schema, the description usefully compensates by enumerating the 12 return formats, and it covers the alpha-override rule. It stops short of describing the actual response structure or error handling for unsupported color strings, which would make it fully self-contained.

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

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

Schema description coverage is 100%: the schema already documents the accepted color notations and alpha's 0–1 range and override behavior. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (converts) and resource (a color) and enumerates all 12 output targets, so an agent knows exactly what it gets back. This also implicitly distinguishes it from the narrower sibling swiftui_color, which covers only one of those formats.

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

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

Usage is implied by the format list — use this when you need one or many platform color representations — but there is no explicit when-to-use guidance and the sibling swiftui_color is never named as the narrower alternative. Nothing is misleading, but routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: unit auto-detection by magnitude, the accepted string dialects, the literal "now", and the fact that a timezone-parameterized wall-clock value is returned. No output schema exists, so this disclosure of shape carries weight.

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. The core action is front-loaded, then a compact enumeration of inputs and outputs; every clause adds usable 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?

With no output schema, the description compensates by naming the returned fields (seconds, millis, micros, ISO 8601 UTC, RFC 7231 UTC, timezone wall clock, relative description), and it covers both parameters and all input forms. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: that epoch seconds/milliseconds/microseconds are auto-detected by magnitude and that a relative human description is produced. It also confirms the timezone parameter governs the wall-clock output, reinforcing the schema's own wording.

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

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

States a precise verb+resource ("Converts between Unix epoch timestamps and human-readable dates") and immediately enumerates which input formats are accepted and which output representations are produced. An agent knows exactly what this does and it is unmistakably distinct from the other utility siblings (hash_text, generate_uuid, convert_color).

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 accepted-input enumeration implicitly tells the agent when the tool applies (timestamp or date string in hand), but there is no explicit when-to-use/when-not statement or named alternative. With unrelated siblings there is little routing ambiguity, so implied usage is adequate rather than strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: cryptographic randomness, the strict ordering guarantee for v7 batches, and the supported output formats. It doesn't describe the return shape, but with no output schema that is a minor gap.

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?

A single compact passage front-loads the core action, then the variants, then formatting and the count bound. Every clause carries information; 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?

Five optional parameters, all fully documented in the schema, and the description covers the one semantic detail the schema can't (v7 ordering) plus the 1-100 bound. With no output schema required and annotations covering the safety profile, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining what each version actually means (v7's time-ordered, strictly-ordered-batch property) and by naming the three formatting modes. It adds real meaning rather than restating the enum.

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

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

States a specific verb (Generates) and resource (UUIDs) and enumerates the exact variants produced: v4, v7, and NIL. No sibling tool in the set produces identifiers, so the purpose is unambiguous at a glance.

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 characterizes each version (v4 = random, v7 = RFC 9562 time-ordered, NIL), which implicitly guides selection, but never frames it as guidance or states when one variant is preferable. There is no explicit when-to-use/when-not or alternative named, leaving the choice to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world behavior. The description goes beyond them by stating statelessness, that input is not stored, and that HMAC-MD5 is unsupported—an important capability limitation that annotations don't capture. Minor gaps (no error behavior for invalid keys) keep it from a 5.

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

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

Two sentences, each earning its place: the first states capability and the HMAC exception, the second states statelessness. Front-loaded and waste-free.

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 read-only hashing tool with full schema coverage and annotations, the description is nearly complete. It could mention output shape (hex string? base64?) but without an output schema that's a small gap, not a blocking one.

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 both parameters are fully described in the schema. The description reinforces the UTF-8 input and HMAC interpretation but adds no syntax, format, or constraint details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description names the exact operation (computing digests), the specific algorithms (MD5, SHA-1, SHA-256, SHA-384, SHA-512), the input type (UTF-8 string), and the HMAC variant condition. It is instantly distinguishable from siblings like generate_uuid or convert_color, which do entirely different things.

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 tells the agent to use this when hashing text, and clarifies the HMAC path when a key is present. But it offers no explicit when-to-use vs alternatives, no exclusions, and doesn't mention sibling tools (which are unrelated anyway). Adequate but leaves routing to inference.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds useful behavioral context about what is actually produced (extension snippet, Asset Catalog Contents.json), which matters since there is no output schema.

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

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

A single dense sentence with the verb and resource front-loaded and zero filler. It is long but every clause names a distinct output format, so it earns its length.

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, the description compensates by enumerating the returned artifacts, and the annotations cover safety. Only minor gaps remain, such as whether the snippet is returned as text and how the pieces are separated.

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

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

Schema description coverage is 100%, so name, alpha, and color notations are fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Generates') and a precisely scoped resource ('every SwiftUI Color initializer for a color'), then enumerates the concrete output formats. This clearly differentiates it 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?

Usage is implied by the output list — an agent can infer this is for producing SwiftUI color code rather than generic conversion — but there is no explicit when-to-use or when-to-prefer-convert_color guidance and no stated prerequisites.

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