QRFLOW.codes

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

Annotations already indicate this is a mutating, non-idempotent operation, so the description only needs to add context. It adds plan gating, quota consumption, and the return behavior including rejected rows, which are useful behavioral details beyond 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 information-dense sentences with zero filler: the action and limit, the alternative for free users, and the row format plus quota and return behavior. Everything 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 single-parameter bulk creation tool with an output schema, this description covers what the tool does, when to use it, plan constraints, quota impact, input shape, and return behavior. Nothing essential 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 must carry parameter meaning. It explains rows as [{destination, label?}], clarifies that destination is a web address, and notes accepted forms like url/link/bare string. It does not define 'label' beyond being optional, but the core parameter semantics are covered.

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 many dynamic URL codes at once'. It also explicitly contrasts with the sibling create_qr_code by noting the free plan should use the one-at-a-time tool, so an agent can distinguish them without opening either 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?

Provides explicit when-to-use guidance: Premium is required, and 'on the free plan use create_qr_code one at a time'. It also names the exact alternative tool and adds the monthly bulk allowance constraint, leaving little 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 cover the safety profile (not read-only, non-destructive, non-idempotent, closed-world), and the description adds substantive context beyond them: the GTIN check digit is validated server-side, a GTIN is unique to one product, and the call is gated to Business plans. It stops short of saying what error arises on a duplicate GTIN or license failure.

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, front-loaded with the action and its outcome, then constraints. No filler, though the checkout/QR framing is slightly promotional relative to the operational facts.

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 output schema exists, so return values need no explanation, and the description covers validation, uniqueness, and plan gating for a 4-parameter mutation. Only the duplicate-GTIN failure mode is left unstated, which for a non-idempotent create is a meaningful but small 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 coverage is 75%, and the description adds a hard constraint the schema does not convey — the GTIN must be a genuine GS1-licensed value whose check digit is verified on submission. The brand field remains undocumented in both places, keeping this below a 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 and resource ('Create a GS1 Digital Link product from a GTIN') and explains the resulting artifact — a QR that scans at checkout and resolves to the brand's URL. This cleanly separates it from create_qr_code, which produces a code without the GS1 product record.

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?

'Business plan only' and 'One GTIN is one product' give real preconditions, and the url parameter hints at the deferred-link workflow. But there is no explicit statement of when to use this versus create_qr_code or bulk_create_qr_codes, and no guidance on what to do if the GTIN already exists.

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 annotations providing only readOnly=false, the description carries the behavioral burden. It discloses the dynamic vs static behavior, the account-based limitation on dynamic codes, and instructs the caller to check the `dynamic` field in the result. It also states the key return values (printed short link and image URL), going well beyond 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?

The description is compact and front-loads the core purpose, then provides necessary detail on kinds, fields, dynamic behavior, and return values. It is dense but not padded; every sentence contributes useful information, though the long list of kind examples makes it slightly heavier than necessary.

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 (8 parameters, nested fields) and the existence of an output schema, the description covers the most important contextual gaps: how to specify kinds and fields, what dynamic means, and what the response contains. It does not mention the relationship to bulk_create_qr_codes, but the rest of the calling context is well addressed.

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 63%, so the description must add meaning to the less-covered parameters. It does: `kind` is explained as a catalog id with examples, and `fields` is illustrated with concrete structures for url, wifi, and instagram. This meaningfully supplements the schema, though it does not address color, frame, or domain parameters, which are left to 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 opens with a clear verb and resource: 'Create a QR code.' It goes on to specify the kind catalog and field structures, making the tool's function obvious. It does not explicitly differentiate from the sibling bulk_create_qr_codes, though the singular phrasing implies a single code.

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 useful context on how to construct a request, such as calling list_code_kinds for the full kind list and providing field examples for url and wifi. It does not, however, explicitly state when to choose this tool over bulk_create_qr_codes or when a different tool would be more appropriate.

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 mark the tool as destructive and idempotent, but the description adds important behavioral context: scan history is permanently deleted and dynamic links stop working. This helps the agent understand the real-world consequences beyond the annotation flags.

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 just two sentences with no filler. It front-loads the core action and consequence, then immediately provides the alternative usage guidance.

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 destructive delete tool with output schema and sibling context, the description is sufficient. It covers what is deleted, the downstream effect, and when to choose a sibling alternative, leaving no critical gap for an agent to call 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 schema has only one required parameter, id, with zero description coverage. The description refers to 'a QR code' and conveys that id identifies the QR code, but it does not explain the id format or how to obtain it. Since the parameter is simple and self-explanatory, the risk is low, but the description does not fully compensate for the missing 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 action ('Delete a QR code') and the resource, and adds specificity by noting scan history is also removed 'for good'. It also distinguishes itself from the sibling update_qr_code by contrasting permanent deletion with pausing.

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 tells the agent when not to use this tool: 'prefer update_qr_code with paused=true if the print is still out there.' This is a direct usage rule that routes to the correct sibling alternative.

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 and destructiveHint=false, so the safety profile is provided. The description adds context about what information is returned (plan, limits) but does not disclose additional behavioral traits such as authentication requirements or whether the info is cached. It is consistent with annotations, and the bar is lower given the existing hints.

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, tight sentence that immediately answers the core question (who is signed in) and then lists the key data points (plan, limits). Every phrase 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?

Given the tool has no parameters, existing annotations for safety, and an output schema, the description fully covers the tool's purpose and scope. It clearly describes the type of information returned, and nothing important for correct selection appears 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 and schema coverage is 100% (trivially). With no parameters to document, the description doesn't need to add parameter semantics. The baseline for zero-parameter tools is 4, and the description does nothing to reduce 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?

The description clearly identifies what the tool does: reports the signed-in user, their plan, and applicable limits. It uses a specific, informative structure that distinguishes it from all sibling tools, which are all QR-code-centric and none of which relate to account or plan information.

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 account, plan, or rate-limit context is needed. It does not explicitly name alternatives or exclusions, but because no sibling tool covers this domain, the usage context is clear and 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing what comes back — 'every link behind it and the address printed on the pack' — giving the agent a sense of payload richness not in 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?

Two sentences, both earning their place: the first defines the result, the second supplies the input constraint. The payload summary is front-loaded before the format detail.

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 the description needn't enumerate return fields, and the single parameter's mechanics are fully covered by schema plus the length note. Annotations carry the safety profile, so 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 goes further by enumerating the accepted GTIN lengths (8, 12, 13 or 14 digits), which the schema does not state. That is a genuinely useful validation constraint beyond the structured field.

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 (get) plus resource (GS1 product) and singles out the retrieval scope with 'One GS1 product by its GTIN', which plainly separates it from the sibling list_products. An agent can select it without opening the 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?

The phrase 'by its GTIN' implies the precondition that you already hold an identifier, which distinguishes it from list_products, but no alternative is ever named and there are no explicit when-not conditions. Usage is inferable 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 cover readOnly/destructive/openWorld, so the bar is lower, and the description still adds real context by defining the non-obvious 'went_nowhere' metric as scans that reached the product with no destination. It leaves out other behavioral facts an agent would want, such as whether the breakdowns are always returned and how time windows aggregate.

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 what is returned and followed by a gloss on the one metric that needs it. The 'went_nowhere' explanation is narrative but earns its place because the term is otherwise opaque; minor tightening possible.

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 existence of an output schema means return values need not be explained, and the annotations cover the safety profile. However, the description promises breakdowns 'by country, device, link type and batch' while the schema exposes no grouping controls, leaving it ambiguous whether those are fixed facets or optional, and it omits the time-window parameter entirely.

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 full burden, yet it says nothing about either parameter. 'days' (default 30, max 365) is never mentioned, so an agent gets no signal about the lookback window, and 'gtin' format/expectations are only indirectly hinted at by 'one GS1 product'.

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 ('Scan counts for one GS1 product') and enumerates the breakdown dimensions (country, device, link type, batch). The scope 'one GS1 product' implicitly separates it from the sibling get_scan_stats, but the description never names or contrasts that alternative 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 by the scoping phrase 'for one GS1 product'; there is no explicit when-to-use or when-to-prefer-get_scan_stats guidance despite that sibling clearly overlapping. No prerequisites, no exclusions, no mention of when the breakdown dimensions matter.

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 and destructiveHint=false, indicating a safe read operation. The description adds minimal extra behavioral context beyond the field listing; it does not mention potential errors (e.g., not found) or response shape, but the output schema covers the response. For a read operation with these annotations, this 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 a single sentence with no filler. It front-loads the primary action and ID reference, then enumerates the return fields compactly. This is an efficient communication that earns every word.

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 single-parameter, read-only tool with a detailed output schema, the description covers the essential purpose and returns. The absence of error handling details and sibling differentiation is offset by the output schema and the obvious nature of the operation. Completeness is high.

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. The sole parameter, 'id', is self-explanatory as the identifier of the QR code. The description implies that 'id' is the identifier and does not add format-specific details, but given the simplicity and that the output schema is richly described, 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 clear verb ('Get') and resource ('QR code by id'), and lists the specific fields returned (what it opens, dynamic status, short link, scan count, image URL). This distinguishes it from siblings like get_qr_image and get_scan_stats, which focus on specific aspects. However, it does not explicitly name the alternative tool for those narrower queries.

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 implies that this tool is for retrieving all details of a single QR code, which is distinct from list_qr_codes (for listing), get_qr_image (for images only), and get_scan_stats (for scanness only). It does not state explicit exclusions (e.g., 'Use this when you need full details, not just image or stats'), but the field list makes the intended use clear.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses meaningful behavior: the PNG is inline and frameless, download links are signed and valid for 24 hours with no sign-in, and the SVG is the print-ready version with frame, colors, and logo. This adds substantial context about what the tool returns and how the links behave.

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 primary purpose and then efficiently explains return formats, link behavior, and the size parameter. Every sentence adds useful information without redundancy, and the length is appropriate for the tool's complexity.

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 key workflow context ('Call this after create_qr_code'), return formats, and link expiry. An output schema exists, so return-value details need not be repeated. The only minor gap is not explicitly naming the id parameter, but the sequencing hint makes it inferable.

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, the description must compensate. It explains 'size is the PNG width in px (256-2048),' which adds semantic meaning beyond the schema's min/max/default. However, the required 'id' parameter is only implicitly referenced via 'Call this after create_qr_code,' leaving its role under-specified.

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: 'Show the user their QR code, or hand them a file to save.' It clearly identifies the tool as returning the QR image, distinguishing it from sibling tools like get_qr_code by focusing on image retrieval and download links.

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 usage context: 'Call this after create_qr_code.' It also describes two use cases—displaying inline or saving via download links—which helps an agent decide when to invoke it. It does not explicitly contrast with get_qr_code, but the sequencing and output details provide sufficient 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 mark the tool read-only and non-destructive; the description adds useful behavioral constraints: the default 30-day window, the 92-day maximum, and the available grouping dimensions. It does not discuss pagination or rate limits, but for a read-only analytics call with an output schema 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?

A single sentence packs the resource, window constraint, and grouping options with no filler. It is front-loaded with the core purpose and keeps the constraint detail compact.

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, return values do not need description. The definition covers the essential call semantics: one code, date window, and grouping. It could mention that only id is required, but the schema already marks it required, so nothing critical 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 50%, and the description compensates by explaining the window semantics (default 30 days, max 92) and listing the group enum values. It also clarifies that the id refers to a single code. It does not add detail about ISO date formatting, but the schema already provides that.

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 resource ('scan analytics for one code') and the scope ('over a window', 'grouped by...'), which clearly distinguishes it from siblings like get_qr_code or list_qr_codes. Although it lacks an explicit verb, the title 'Get scan statistics' supplies it, so an agent can tell what this tool does.

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 the tool is for retrieving per-code analytics over a date range, but it never states when to prefer it over alternatives or when not to use it. There is no explicit exclusion or pointer to sibling tools, so an agent must infer usage from the phrase 'one code'.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful context about the return content: it includes the fields each kind needs and the required plan, which goes beyond the structured 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?

Two sentences deliver the core purpose, the scope, the return content, and usage guidance. The enumeration is long but directly useful, and no words are wasted.

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 parameters, an output schema present, and annotations covering safety, the description supplies the remaining essential context: what the tool returns and when to use it. Nothing needed 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?

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to clarify. The baseline of 4 applies because there is nothing for the description to add.

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 ('List') and resource ('kinds of QR code QRFLOW can make'), and enumerates concrete examples. This clearly distinguishes it from sibling tools like create_qr_code or get_qr_code.

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 instructs when to call the tool: 'Call this before create_qr_code when unsure which kind or fields to use.' This names the relevant alternative and provides a clear decision rule.

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 indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that it returns the default domain and ids, which is useful. However, it doesn't mention the output schema's structure (which exists), so the agent may not know the exact format of the response. The description adds some value beyond annotations but not extensive.

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 sentence, front-loaded with the main function. It includes specific details (default, ids) without verbosity. It could be slightly more structured but is efficient.

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, read-only) and has an output schema, so the description doesn't need to explain return values. It covers the purpose and key output aspects. Given the low complexity, the description is sufficient for an agent to call 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 tool has no parameters, and schema description coverage is 100% (empty schema). The description provides context that the tool returns default and domain_id values, which adds meaning to what the tool returns, but there are no parameters to explain. With zero params, a 4 is appropriate as the description informs about return values that are otherwise not in 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?

States a specific verb and resource ('List link domains'), and clarifies that it returns domains, the default, and their ids for domain_id. Distinct purpose, no ambiguity.

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?

Implied usage is to retrieve domains info when the agent needs to know domain_id or default domain. No explicit guidance on when NOT to use or alternatives, but the narrow scope makes it clear it is for listing domains only, unlike other sibling tools which are for QR codes and account info.

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 the safety profile is covered. The description adds the non-obvious plan-tier restriction, which the agent cannot see anywhere in the structured fields and which would otherwise cause a failing call.

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 resource and followed immediately by the retrieval restriction. Every clause carries information: what it returns, what fields each record holds, and who can call it.

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, the description need not explain return shape, and it correctly stays out of that. Read-only status, plan gating and the searchable fields are all covered; only the absence of any guidance on result volume relative to 'limit' keeps it from a 5.

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%: 'q' documents search over names/GTINs, and 'limit' is self-evident from its default 25 and 1-100 bounds even without prose. The description adds no filtering or pagination semantics, so the description neither compensates for nor widens the gap — baseline 3.

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 (List) plus a precisely named resource (GS1 Digital Link products), with a clarifying gloss ('the codes that go on retail packaging') that separates it from list_qr_codes and list_code_kinds. It never explicitly names the sibling it is not, so it stops short of 5.

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?

'Business plan only' is a genuine eligibility gate an agent must check before calling, which is more than most list tools offer. However, there is no statement of when to use this versus get_product (single lookup) or list_qr_codes, so routing is left to inference from the name.

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 mark the tool as read-only and non-destructive. The description adds useful behavioral context by specifying sort order ('newest first') and included fields ('scan counts and the printed short link'), but it does not mention pagination or other response traits. This is comparable to the baseline where annotations cover the safety profile.

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 short sentences with no filler. The core action and ordering are front-loaded, and the optional search behavior is stated concisely in the second 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?

For a simple read-only list with an output schema, the description covers the resource, ordering, and key return fields. It omits the limit parameter's meaning, but the schema's constraints partially cover it and the output schema handles return details. Overall adequate with a small 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?

The schema already documents q as 'Search labels', and the description only repeats that without adding new meaning. The limit parameter has no schema description and is not mentioned in the tool description, so its semantics are left to inference from default/min/max. With 50% schema coverage, the description should have compensated but did not.

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 ('List'), identifies the resource ('the account's QR codes'), and adds ordering and return fields ('newest first, with scan counts and the printed short link'). This clearly distinguishes it from sibling tools like get_qr_code or list_code_kinds.

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 the list operation and mentions optional label search, but it does not explicitly state when to prefer this over siblings like get_qr_code or list_code_kinds, nor does it provide exclusions. Usage is implied rather than directly 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 declare idempotentHint=true and destructiveHint=false; the description reinforces this by saying a re-run with the same type and batch replaces rather than duplicates. It also discloses a non-obvious side effect: a batch-scoped link only applies to codes carrying that batch. It does not cover failure modes or what happens to existing links of other types.

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, each carrying distinct information: action, resolution behavior, batch scoping, and idempotent replace. Front-loaded with the core action and 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?

For a mutation tool that already has annotations and an output schema, the description covers the key behaviors an agent must know before writing: idempotency, batch scoping, and default routing. Missing are error/permission expectations and any mention of validating link_type values beyond the pointer in the schema.

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?

At 67% schema coverage the schema already documents batch, title, link_type, and is_default. The description adds the interplay between them – which link a phone resolves versus which an app requests, and that batch narrows scope. It says nothing extra about gtin or the format of url.

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 concrete action on a concrete resource: pointing a product's GS1 link type at a URL. The default-vs-specific-type sentence makes the semantics clearer than the title alone. It stops short of naming a sibling (e.g. update_qr_code) to disambiguate, so a 4 rather than a 5.

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 real usage scenario – batch scoping 'which is how a recall is done without touching other stock' – and explains the default vs type-specific routing decision. It offers no explicit exclusions or 'use X instead' routing to the many sibling tools, which keeps it at 4.

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?

The description reveals a non-obvious runtime behavior: 'the printed code keeps working' after destination changes, which is valuable beyond the idempotent/destructive annotations. It also notes the dynamic-code-only restriction for destination fields. No contradiction with 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?

A single information-dense sentence with no filler; the key instruction 'Send only what changes' is included after the field list. 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 12-parameter update tool with a low-coverage schema, the description covers the most important caveats (dynamic-only, partial update, printed-code behavior) but leaves exact field groupings and value formats (colors, frame styles, domain_id semantics) unspecified. Annotations and output schema fill some gaps, but not all.

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 only 25% schema coverage, the description adds meaning by explaining slug as 'link name on the account's domain', expires_at as 'ISO or null', and destination fields as dynamic-code-only. However, 'colors, frame' is a loose mapping to bg_color/fg_color/frame_style/frame_caption and does not specify allowed values, so it only partially 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 description identifies a specific operation—'Change a QR code'—and enumerates the updatable fields, so an agent can tell it apart from create/delete/list siblings without opening the schema. It does not explicitly name siblings or state 'existing code', but the verb and 'Send only what changes' make the update semantics 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?

'Send only what changes' gives a clear partial-update usage rule, and 'dynamic codes only; the printed code keeps working' provides an explicit when/where constraint for destination changes. It does not describe scenarios where create_qr_code would be preferred, but the context is sufficient for an agent to avoid misusing it.

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