QRMint by Harlo

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds genuinely new behavioral facts: check digits are auto-added or verified, output is format-valid but not GS1-registered, and scannability depends on contrast, print size, quiet zone and reader. These are limitations an agent could not derive from 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?

Four compact sentences with no filler: capabilities first, then input convention, then exclusions, then caveats. Each clause carries distinct information and the most decision-relevant facts (symbologies, formats, static-only) are 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?

With no output schema, the description correctly tells the agent what comes back (SVG/PNG/data URL) and sets expectations about validity and scannability. It is nearly complete for an 8-parameter tool, with the only gap being the unaddressed styling and sizing parameters.

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, and the description only adds meaning for three of them: symbology, format and data (with its check-digit convention). The bg, fg, size, height and margin parameters receive no semantic guidance in either place, so compensation is partial.

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 states the exact symbologies (Code 128, EAN-13, UPC-A, EAN-8) and output formats (SVG/PNG/data URL), so the resource and result are unambiguous. Combined with the title's verb, an agent can distinguish this from the qr_* siblings (2-D) 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?

"Static codes only: no redirects, no dynamic/editable codes, no scan analytics" gives explicit when-not guidance, and the check-digit rule tells the caller how to supply EAN/UPC data. It stops short of naming qr_generate as the alternative for 2-D codes, so sibling routing is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive behavioral context beyond them: per-format size ceilings, the SVG-only bulk endpoint with item/count limits, the warning that EAN/UPC output is format-valid only and not GS1 registration, and an explicit non-guarantee of scannability due to contrast, print size, quiet zone and reader. That is unusually rich disclosure for a generator.

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 dense sentences with zero filler, front-loaded with the core output formats and size limits, then constraints, then caveats. Each sentence adds distinct 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 and 8 optional parameters, the description still conveys the return shape (SVG markup, PNG base64, or data URL) and the salient limits. The main gap is the relationship between data and payload and the defaults for bg/fg/ecc/margin, which an agent must guess.

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; it explains the format parameter's three values and the size ceiling that varies by format, which is genuinely useful. But bg, fg, ecc, margin and the data-vs-payload distinction (mutually exclusive? which wins?) are never addressed, leaving over 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 ('Generate a static QR code') and immediately narrows scope: SVG default up to 2000 px, PNG base64 or data URL up to 1024 px, from data or a payload object. The 'static codes only: no redirects, no dynamic/editable codes, no scan analytics' clause cleanly separates it from dynamic-QR style siblings, though it never names qr_payload_build, qr_inspect or barcode_generate directly.

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

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

Gives explicit when-not conditions (no redirects, no dynamic/editable codes, no analytics) and notes the bulk path with its own limits (SVG-only, ≤50, ≤256 bytes per item). It does not tell the agent when to prefer qr_payload_build to construct a payload first or qr_inspect to verify output, so routing against siblings is only partially solved.

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, non-destructive, and closed-world, so the safety profile is fully covered structurally. The description adds only the returned-signal list and the 'No image' confirmation, without disclosing validation behavior details (e.g. whether capacity % fails hard or warns).

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 sentence that front-loads the return payload and ends with the key exclusion ('No image'). 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, zero schema coverage on four params, and a nested payload object, the description leaves the agent guessing at input semantics and return shape. The output-list sentence helps but does not compensate for the undocumented nested object.

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

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

Schema description coverage is 0% for four parameters, including a nested `payload` object, an `ecc` enum, and a `margin` integer. The description alludes only loosely to 'ECC' and 'quiet-zone' without mapping them to parameter names, and does not explain the relationship between `data` and `payload` or acceptable `margin` units.

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 (Return) and enumerates exactly what is returned: version, ECC, module count, capacity %, and quiet-zone/density warnings. The 'No image' clause distinguishes it from the sibling qr_generate, though that differentiation is implicit rather than by name.

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 no when-to-use guidance, no exclusions, and does not name any alternative. 'No image' hints at the boundary with qr_generate but never states 'use qr_generate for an image, use this to validate capacity.' The agent must infer the workflow context.

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 safe, read-only, idempotent, closed-world profile, so the description's added value is stating that it validates and returns a string rather than an image — genuinely useful given there is no output schema. It stops short of saying what happens on an invalid payload (error vs. partial string).

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 tight sentences with the verb and type list front-loaded and the return-shape caveat at the end; every clause carries information. No filler or restatement of the tool name.

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 taking a nested, schema-undocumented object across eight payload types, the description supplies only one worked example, so an agent cannot reliably construct vcard, geo, mailto, tel or sms payloads. Validation semantics (what constitutes invalid, what error looks like) are also unstated, leaving substantial gaps for this level of schema 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% and the single parameter is a free-form nested object whose schema only pins the 'type' enum, leaving per-type keys undefined. The wifi example (ssid, password) adds real meaning the schema lacks, but it documents only one of eight types, so mailto/vcard/geo/sms required fields remain guesswork.

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 pair (build and validate) and resource (QR payload string), and enumerates the supported payload types, which is more than the title alone conveys. It implicitly separates itself from qr_generate with 'Returns the string only', but never names a sibling outright.

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

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

Usage is only implied: an agent must infer that this is the step before qr_generate/qr_inspect and that it is the right tool when you want a payload string rather than an image. There is no explicit when-to-use, when-not-to-use, or named alternative.

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