useSignal

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the exact set of conversions returned (ISO, UTC, epoch seconds/ms, relative time, localized time) and that both second and millisecond inputs are accepted. It does not say what happens on invalid input, so not a 5.

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

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

A single front-loaded sentence with no filler; every clause (input formats, output formats, time zone) carries information an agent needs.

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

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

With no output schema, the description correctly enumerates the returned representations, and the 2-parameter surface is fully covered between description and schema. Only error/invalid-input behavior is unaddressed, a minor gap for a pure conversion utility.

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

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

Schema coverage is 50%: timeZone is documented in the schema, but 'value' has no description there. The description compensates by defining exactly what 'value' accepts (Unix seconds or milliseconds, or an ISO 8601 date) and by explaining that timeZone drives the localized output. This adds meaning beyond the schema.

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

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

Specific verb (Convert) plus resource (Unix timestamp / ISO 8601 date), and it enumerates the exact output formats produced. An agent can distinguish this from the unrelated siblings (regex, cron, QR, JSON tools) instantly.

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 scopes usage by naming the accepted input formats (Unix seconds/milliseconds, ISO 8601), which tells the agent when this tool applies. However there is no explicit when-to-use/when-not guidance or named alternative, since the siblings are unrelated utilities. Minimum viable.

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 and closed-world, so the safety profile is covered. The description still adds real behavior beyond that: numbers compare exactly, arrays match by content by default so an inserted item counts as one addition, and position mode compares index by index. That is meaningful semantics an agent could not infer from the annotations.

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

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

Three tightly packed sentences with zero filler, front-loaded with the core purpose before the comparison semantics and the mode switch. 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 state the return shape (added/removed/changed values with JSONPath), and annotations cover safety. The remaining gaps are the left/right orientation and no mention of the 200,000-character input limit or how large diffs are returned, but for a 3-parameter diff tool this is close to 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 carry the parameter burden. It fully documents the arrays enum (content vs position, and the default), but says nothing about left/right beyond the implicit 'two JSON documents' — notably which side is the baseline for 'added' vs 'removed' — leaving directionality ambiguous.

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

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

The description gives a specific verb and resource ('Compare two JSON documents structurally') plus the exact deliverable ('list every added, removed and changed value with its JSONPath'). That is clearly distinct from siblings like usesignal_format_json or usesignal_encode_decode, so an agent can route without opening any schema.

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

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

Usage context is only implied: the description explains the default array-matching mode and when to switch to arrays:"position", which is parameter-selection guidance rather than tool-selection guidance. It never states when to reach for this tool over usesignal_format_json or any other sibling, nor any exclusions or prerequisites.

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, closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: Base64 is UTF-8 scoped, and critically that the JWT signature is NOT verified, which prevents an agent from misrepresenting decoded tokens as validated.

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

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

One dense sentence lists the operations, followed by a one-line usage directive. Every clause earns its place and the operational scope is front-loaded with no filler.

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

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

With no output schema, the description still hints at return shape for JWT (readable exp/iat/nbf dates). Return format for the encode/decode/hash paths and the hash-algorithm selection mechanism remain unstated, leaving a small but real gap for a 6-operation 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 carry parameter meaning. It clarifies the 'text' payload and maps well to the operation enum values, but it never explains how the hash algorithm (MD5/SHA-1/SHA-256/SHA-512) is selected given that the schema exposes only 'operation' and 'text' — a real ambiguity the description should resolve.

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 resource (text transforms) and enumerates every supported operation: Base64, URL encode/decode, JWT decode, and four hash algorithms. It is immediately distinguishable from siblings like usesignal_test_regex or usesignal_format_json, and the operations align 1:1 with the schema enum.

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

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

It gives a direct directive: 'Use this instead of computing hashes or Base64 by hand,' which establishes when to reach for it. It stops short of any when-not guidance or sibling routing, but the siblings are functionally unrelated, so the omission is minor.

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 bar is low. The description goes further by disclosing the output form (plain English plus next run times) and the non-obvious DST-handling behavior, which is genuinely useful. It stops short of saying what happens on a malformed expression or how the 'count' cap behaves.

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

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

One dense sentence with no filler; the core action is front-loaded and the qualifiers (field layout, time zone, DST) follow. It is efficient, though the parenthetical field enumeration makes it slightly heavy for a single sentence.

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 correctly carries the return-value burden, naming both the explanation and the next-run list, and covers the DST subtlety. The remaining gap is the undocumented 'count' parameter and error behavior for invalid expressions.

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

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

Schema coverage is only 33% (only timeZone is documented in the schema). The description partially compensates by explaining the expression format (5 fields, with their meanings) and the time-zone input, but 'count' is never mentioned in either place, leaving its meaning to be inferred from the name and default of 5.

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

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

States a specific verb ('explain') and resource ('standard 5-field cron expression'), plus the two outputs (plain-English explanation, next run times) and the time-zone/DST scope. It is unambiguous what the tool does, though it does not differentiate itself from any sibling since none of the other listed tools touch cron.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for cron expressions, but there is no explicit 'use this when...' framing, no when-not guidance, and no named alternative for related tasks such as timestamp conversion (usesignal_convert_timestamp).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing both return artifacts (Mermaid source and SVG) and the steps-mode line syntax, going beyond the structured fields.

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 front-loaded sentences that state the core transform first, then the steps-mode syntax detail. Little waste, though the syntax example could be slightly tighter.

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?

A read-only transformation tool with no output schema, so the description is right to name the outputs. It covers mode/input adequately but omits the direction parameter, leaving a small gap for a three-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the three mode inputs and gives concrete steps-mode syntax with branch examples, but says nothing about the direction parameter (vertical/horizontal), leaving one of three parameters undocumented.

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

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

States a specific verb (turn ... into) with the exact input types and the concrete output (Mermaid source and SVG diagram). No sibling tool produces flowcharts, and the description makes the resource 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 implies three input sources via the mode names but never states when to choose code vs steps vs mermaid, nor any exclusions or prerequisites. Usage is inferable but not explicitly guided.

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, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: invalid input yields exact line/column diagnostics, repair defaults to on, and each applied fix is listed — information the annotations cannot convey.

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

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

Two sentences, zero waste, and well front-loaded: the first states what the tool does, the second details error and repair behavior. Both sentences earn their place by adding information the schema does not contain.

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

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

With annotations covering the safety profile and no output schema to explain, the description supplies the remaining essentials: modes, repair default and semantics, and diagnostic behavior. It stops short of describing the response shape (formatted output vs. fix list), but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description carries the param burden, and it does substantial work: it documents mode (format/minify), sortKeys, and repair (including its default of true and what it fixes). Only the indent enum values ('2'/'4'/'tab') go unexplained, which is a minor 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 description opens with three specific verbs (validate, pretty-print, minify) applied to a named resource (JSON), plus the optional key-sorting capability. This is clearly distinguishable from siblings like usesignal_diff_json or usesignal_encode_decode, which operate on different resources.

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 through the mode keywords (format/minify) and the repair behavior, so an agent can infer when this tool applies. However, there is no explicit 'use this when' guidance and no reference to alternative sibling tools (e.g. diff_json), leaving 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them by disclosing the return contents (shade scale, contrast checks, CSS/JSON/Tailwind exports) and a scope caveat about contrast measurement limits.

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

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

Three tight sentences: capability and input first, then outputs, then the limitation and the follow-up call. Every sentence earns its place with no filler.

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

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

With no output schema, the description compensates by enumerating the return artifacts, and annotations already cover safety and determinism. Purpose, input, outputs, limitation, and next step are all present for a simple single-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does: the input is a 'six-digit hex brand color', which matches the schema pattern and explains the format's intent. Minor gap: it doesn't clarify case handling or whether the '#' is required, though the pattern implies it.

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 (Generate) and resource (light and dark semantic color tokens) plus the exact input form (six-digit hex brand color). No sibling tool overlaps with color-token generation, so no disambiguation is required.

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

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

Gives a clear usage boundary ('This measures listed color pairs only, not whole-page accessibility') and a concrete next step ('Call usesignal_open_workbench with the result input to preview'). It lacks an explicit when-to-use-vs-alternatives statement, but no sibling competes, so the context 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered; the description still adds real value by disclosing in-memory processing, the secrets caveat, and how arrays/nulls are rendered as JSON textareas. It does not cover size limits or error behavior, so it stops short of full.

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

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

Four short sentences, purpose front-loaded, then outputs, then edge-case behavior, then the sibling routing hint. Nothing is redundant and every sentence carries information an agent would otherwise have to guess.

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

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

There is no output schema, and the description compensates by enumerating the five export formats returned. Combined with the annotations, a caller knows what it gets and that the call is safe, but the undocumented overrides parameter leaves a gap for callers wanting to customize the generated form.

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% across 3 parameters. The description clarifies that the required 'json' string is a serialized JSON object and hints at nested paths, but the 'overrides' parameter — by far the most complex, with path arrays up to 9 items, a type enum, labels, and required flags — is never mentioned. It only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Generate an editable form from a JSON object') and immediately enumerates the concrete artifacts produced (nested field paths, JSON Schema, HTML, React JSX, config exports). This distinguishes it from sibling generators like usesignal_generate_qr, usesignal_flowchart, and usesignal_format_json.

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

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

Gives an explicit routing rule: 'To show an interactive preview, call usesignal_open_workbench with this result input,' which tells the agent the follow-up path. It also flags a usage constraint ('avoid secrets'), but no explicit when-not-to-use condition or exclusion is stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds the return contract ('encoded payload, an SVG file and a PNG preview image'), which is valuable since there is no output schema. It does not cover sizing or failure behavior, so it falls just short of 5.

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

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

Front-loads the core purpose and return values before the dense 'values by type' block. The compact mapping notation is information-dense and every token earns its place, though the run-on field list is slightly hard to parse.

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

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

Covers purpose, output artifacts, and the complex nested parameter structure for a 7-param tool with no output schema. Only the visual customization parameters lack explanation, which is a minor gap given their defaults and enums.

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?

With 0% schema description coverage and a generic nested 'values' object, the per-type field mapping (url{url}; wifi{ssid,password,security...}; upi{vpa,name,amount,note}) is essential and well documented, including the WPA|WEP|nopass enum. The styling params (dark, light, margin, moduleStyle, errorCorrection) are left unexplained but are self-evident from defaults/enums.

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

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

States a specific verb+resource ('Generate a scannable QR code') and enumerates every supported payload type (url, wifi, vcard, upi, etc.). No sibling tool produces QR codes, so the agent can immediately distinguish it from the conversion/formatting utilities.

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 enumerated type list effectively tells the agent which scenarios are supported and maps each to its required fields, giving clear usage context. It stops short of explicit when-not or alternative-tool routing, but no sibling overlaps this capability.

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/non-open-world, so the safety bar is met. The description adds genuine behavioral context beyond them: 'Recomputes from validated inputs; no shared state,' which tells the agent the workbench is stateless and derives output from the passed inputs rather than mutating anything.

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

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

Three short sentences, front-loaded with the core action, followed by the required workflow and the state-behavior note. No filler; every sentence 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?

The prerequisites and statelessness are covered, and annotations carry the safety profile with no output schema to explain. However, it never states what 'showing' the workbench actually returns (a UI artifact, a URL, a payload), which is a meaningful gap for a UI-opening tool with a nested-object parameter.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: 'input' is the value returned by a data tool and 'tool' is the matching tool name. This explains the role of both required params. It stops short of detailing the enum constraint or the shape of the nested input object.

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 ('Show the editable useSignal UI') and implicitly distinguishes itself from the sibling data tools, which it references as the prerequisite step. It is clear what the tool produces at a high level, though 'workbench' is left somewhat abstract.

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 an explicit ordered workflow: 'First call a useSignal data tool, then pass its returned input and matching tool name.' This tells the agent exactly when this tool applies (after obtaining results from a sibling). No explicit when-not or named alternative, so not 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that output is served by usesignal.dev (external dependency) and that output includes multiple snippet formats, but the 4000px cap merely restates the schema maximum and no auth or rate-limit context is given.

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

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

Two tightly written sentences with the core purpose and return shape front-loaded and the size constraint trailing. 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?

An 8-parameter tool with zero schema descriptions and no output schema needs the description to carry parameter and return detail, and it does not. An agent can grasp the intent but not how to use style, pattern, radius, background or color correctly.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate and largely does not. It mentions only width/height, repeating the schema's 4000 maximum, and says nothing about text, color, style, pattern, radius or background semantics — leaving half the parameters undocumented anywhere.

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

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

States a specific verb and resource ('Create a placeholder image URL') and enumerates the concrete artifacts returned (URL, HTML, Markdown, CSS snippets). This is clearly distinct from siblings like usesignal_generate_qr or usesignal_generate_colors without needing to name them.

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

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

Gives explicit use contexts — mockups, prototypes, seed data, layouts — which tells the agent when this tool is appropriate. It stops short of naming exclusions or alternative tools, so it is clear context without routing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuine behavior beyond them: a 500ms execution timeout, JavaScript flag semantics, and the return shape ('indexed matches and capture groups'). It stops short of noting limits like the 20000-char text cap or the 50-case test limit.

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

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

Four short sentences, front-loaded with the core purpose, followed by return shape, semantics/timeout caveats, and the follow-up action. No filler; every sentence 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?

No output schema exists, but the description states the return contents (indexed matches and capture groups), covers execution semantics, and points to the highlighting workflow. The main gap is not mentioning the size caps that constrain inputs, which matters for a 4-param tool with an array parameter.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain that 'flags' follow JavaScript semantics and that 'tests' are expected match/non-match cases, which is real added value, but it never explains defaults (flags='g', tests=[]), the maxLength/maxItems constraints, or the required pattern/text relationship.

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

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

States a specific verb and resource ('Execute a JavaScript regular expression against text') plus the expected-test-case dimension, which no sibling provides. An agent can distinguish this from usesignal_format_json, usesignal_diff_json, and the other converter/encoder siblings immediately.

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 purpose (test a regex), and it names a follow-on tool (usesignal_open_workbench) for highlighting matches, which is helpful routing. However, it gives no explicit when-to-use conditions or when-not-to-use exclusions relative to alternatives.

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