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

With no annotations, the description carries the full burden and does well: it discloses immediacy ('live for the next scan, immediately'), the immutability of the printed artifact, and that the prior destination is retained in qrtap_code_history. It omits error behavior (invalid codeId, non-http scheme), permission needs, and reversibility of the change beyond the history reference.

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-loaded with the action and the key invariant, then sequencing effect, audit trail, and the confirmation warning. Slight marketing phrasing ('This is the core of the product') is the only sentence that does not carry operational weight, but it earns some of its place by motivating the confirmation rule.

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?

Two required params, no output schema, and no annotations — the description covers effect, timing, side effects, and the safety ritual an agent needs before mutating customer-facing behavior. What is missing is failure handling (bad codeId, invalid URL, expired code) and any indication of what the call returns.

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 both parameters are already documented, including that codeId comes from qrtap_create_code or qrtap_list_codes. The prose adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Point an existing code at a new destination URL') and immediately clarifies the invariant: the printed QR, slug and short_url stay identical while only the redirect target changes. That distinguishes it cleanly from the creation siblings like qrtap_create_code and qrtap_create_short_link.

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 usage scenario (replacing a menu or price list without reprinting) and a concrete pre-call obligation: confirm the new URL with the user because real customers see the change. It does not name an explicit alternative tool or a 'do not use when' case, which keeps it short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses ordering (newest first), the fields returned (version number, reason, activation timestamp), and a genuinely useful invariant — the printed code never changed, only its target. It stops short of stating whether history is complete/bounded (retention, pagination) or any auth requirements, which is the remaining gap for a no-annotation tool.

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: the return shape is front-loaded, use cases follow, and the closing invariant adds real value. 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?

With no output schema, the description correctly compensates by enumerating returned fields and ordering. It is nearly complete for a one-parameter read tool; only result-set bounds (does history truncate? is it paginated?) are unaddressed.

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

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

Schema coverage is 100% and the codeId property description already explains it is the internal UUID from qrtap_create_code / qrtap_list_codes, not the slug. The description adds nothing about the parameter, so baseline 3 applies — the schema does the work.

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 resource and scope: every destination one code has ever pointed at, newest first, with version number, reason, and activation time. This implicitly separates it from qrtap_get_code (current target) and qrtap_change_destination (mutation) — the phrase 'ever pointed at' and 'recover a previous URL' make the temporal, historical nature 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?

Gives two concrete use cases: answering 'where did this code point last week?' and recovering a previous URL after a wrong retarget. That's clear positive guidance, but it never names an alternative sibling or states when *not* to use it (e.g. use qrtap_get_code for the current target).

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

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

With no annotations, the description carries the burden and does well: it discloses that bots are excluded and that no IPs or user-agents are stored, so no per-person data can be returned. That is real behavioral context an agent could not infer. It stops short of stating auth requirements or aggregation granularity 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 sentences, no filler, front-loaded with what the tool returns, then the privacy note, then the alternatives. Every clause does work.

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, yet the description names the returned fields (total, per-day series, device split), so an agent knows what to expect. With only one required parameter and full schema coverage, nothing material 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 schema already defines codeId, from and to with ISO 8601 formats. The description reinforces the intent of from/to ('bound the window ... when the user asks about a period'), which is mild added value, but adds no new syntax or constraints. Baseline 3 applies.

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

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

States a specific verb and resource ('aggregated anonymous scan statistics for ONE code') and enumerates exactly what is returned: total scans, per-day series, device split. The uppercase 'ONE' plus named sibling alternatives make it unmistakable against qrtap_group_stats and qrtap_list_codes.

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?

Explicit routing: use this for a single code, use qrtap_group_stats for a whole batch, use qrtap_list_codes with include_stats for plain totals across many codes. It also says when to supply from/to ('when the user asks about a period'). Both the when and the when-not are covered.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (id, short_url, png_url/svg_url), the critical immutability guarantee that short_url never changes, and that creation is idempotent by external_ref so retries are safe. It stops short of auth/permission requirements, rate limits, and error behavior on invalid URLs, which keeps it off 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?

Three sentences, front-loaded with the cardinality constraint, then the return contract, then the sibling routing. No filler; the parenthetical about printed stickers never being reissued is the payload that justifies the whole tool's existence.

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, and the description compensates by enumerating the returned fields (id, short_url, png_url/svg_url, plus echoed label/group/external_ref). Combined with 100% schema coverage and the bulk-tool routing, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema description coverage is 100% and the schema already explains url constraints, group bucketing, title default, external_ref idempotency, and design_template_id provenance. The description repeats the external_ref/idempotency idea in conceptual terms but adds no syntax, formats, or constraints beyond what the schema states, so the baseline 3 is appropriate.

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

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

States a specific verb and resource with an explicit cardinality constraint ('Create ONE managed QR code on QRTap') and immediately distinguishes itself from qrtap_create_codes_bulk. An agent can tell exactly what this tool mints and how it differs from the sibling bulk tool 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?

Explicit routing: single code here, 'for more than a handful of codes at once use qrtap_create_codes_bulk instead — it is one request rather than N.' It also points to qrtap_change_destination for the later edit workflow and to qrtap_list_codes for lookup by external_ref, so the agent knows both the boundary condition and the adjacent operations.

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

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

With no annotations, the description carries the full burden and does so well: it discloses per-item results, partial-failure behavior, idempotency via external_ref, the created/reused count semantics, and the paid-plan requirement with HTTP 402 plan_required.

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 main action and max batch size, then packs usage, response shape, idempotency, and plan constraints efficiently. It is slightly dense as one long paragraph, but every sentence contributes useful 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?

Given a bulk-creation tool with no output schema, the description covers the response envelope, per-item success/failure shape, retry behavior, idempotency, and plan restriction. An agent has enough context to invoke and handle results 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 coverage is 100%, so the nested item fields are already documented thoroughly in the schema. The description reinforces external_ref usage but adds little parameter syntax or meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create MANY managed codes') plus the scope ('up to 500'), and distinguishes bulk creation from the single-code sibling by explicitly naming qrtap_create_code as the fallback.

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 concrete when-to-use examples (print runs, tables/shelves, branches/partners), names the alternative for non-bulk cases, and explains the free-plan fallback explicitly.

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

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

No annotations exist, so the description carries the full burden and meets it: it discloses destructive replace semantics, that every omitted field is dropped from the live page, that retries with identical content are idempotent, that the slug is stable so printed QRs keep working, and that the prior version remains in history. The only gap is permissions/authentication, which is minor against this otherwise rich behavioral 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?

Front-loaded with the action and output, then the REPLACE warning, then the correct alternative, then retry semantics — a deliberate ordering that matches decision urgency. Despite its length every sentence carries distinct information; nothing is restated from the schema.

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

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

For a nested-object mutation tool with no output schema, the description supplies return keys (slug, public_url), the downstream hand-off to qrtap_create_code, idempotency behaviour, and history retention — everything needed to call it and use the result 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 100% and the nested content object documents every field, its limits, and server-side sanitisation, so the schema does the heavy lifting. The description adds only the shape summary (name, contacts, price list, review links) and the drop-everything-not-sent contract, not per-field guidance 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?

States a specific verb+resource (create and publish the organization's public page) and pins down what the artifact actually is — a mobile business card at https://app.qrtap.kg/a/<slug> with name, contacts, price list and review links. It also distinguishes itself from qrtap_update_page by name, so an agent can route 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?

Explicitly names the exclusion condition ("Never reach for this tool to add or change something on a page that exists") and prescribes the alternative workflow: qrtap_get_page → merge → qrtap_update_page. It also gives a positive precondition (one page per workspace) that determines whether this call is even legal.

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

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

With no annotations, the description carries the disclosure burden and does well: it states the object is the same managed entity as a QR code, hits the same endpoint, that short_url is permanent, the destination is retargetable, and scans are counted. It does not cover auth requirements or rate limits, but the core behavioral model and mutability semantics are clear.

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 dense sentences, front-loaded with the action and URL format, then the differentiator, then the routing rule. No filler and each sentence carries a distinct decision or behavioral fact.

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 tool with no output schema, the description covers the return value (short_url, permanent), the object's lifecycle (retargetable), tracking (scans counted), and when to pick a sibling instead. Nothing an agent needs to select or 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% for the single url parameter, so baseline is 3, but the description adds real meaning by noting the destination is retargetable later — telling the agent the url is changeable after creation rather than fixed. That is semantics the schema does not convey.

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 short link) and even shows the URL shape 'https://app.qrtap.kg/<slug>'. It explicitly distinguishes itself from qrtap_create_code and qrtap_create_codes_bulk by explaining it is the link-only variant of the same object.

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 trigger ('when the user asks for a LINK rather than a printed code') and an explicit exclusion list ('if they need a label, a group, an external_ref or a batch'). It names the exact alternative tools to use in those cases, leaving nothing 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?

With no annotations, the description carries the burden and does reasonably well: it discloses that the call returns current state plus a 'permanent' short_url, which signals what is stable versus mutable. It does not cover failure behavior (unknown id) or any auth/rate-limit context, so it is not fully complete.

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 the action and scope, followed immediately by the use case. 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?

Since there is no output schema, the description correctly enumerates the returned fields, which is the essential missing piece. It stops short of describing not-found handling or whether the artifact URLs are signed/expiring, minor gaps for a single-parameter read 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 100% and already explains that codeId is the internal UUID rather than the short_url slug. The description adds no syntax or sourcing detail beyond 'by id', so the schema is doing the heavy lifting — 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?

States a specific verb and resource with explicit scope: 'Fetch one code by id', then enumerates the fields returned (destination, label, group, external_ref, short_url, artifact URLs). This clearly separates it from the list-oriented siblings such as qrtap_list_codes and qrtap_code_history.

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 concrete usage contexts: confirm where a code points before changing it, or re-read a previously returned code. It implicitly routes the agent toward qrtap_change_destination workflows but never names an alternative sibling explicitly, so it falls short of full when/when-not 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?

With no annotations, the description carries the burden and does disclose that this is a read that returns current content, plus the critical hazard that qrtap_update_page overwrites content wholesale. It does not cover error behavior (e.g., unknown slug) or any permission/visibility constraints on "public" pages, so it stops short of full behavioral disclosure.

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 what the tool returns, then the workflow, then the sibling exclusion. Every sentence carries distinct routing or behavioral information with no 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?

For a single-parameter read tool with rich schema coverage and no output schema, the description supplies the essential return hint (`content` object) and the reason to call it. It leaves the rest of the page object's shape unstated, which is acceptable given no output schema but is a small remaining 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?

One parameter at 100% schema coverage, so the schema already documents `slug` with an example. The description adds only the implicit notion of scope ("public page") and does not clarify slug format, uniqueness, or resolution rules beyond the schema example — 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+resource ("Read ONE public page in full") with the returned payload named (`content` object). It explicitly separates itself from both siblings that could be confused with it: qrtap_list_pages (omits content) and qrtap_update_page (the write counterpart).

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?

States the exact workflow it belongs to — "read-before-write step for qrtap_update_page" — and gives the procedure (fetch, change one field, send merged object). It also rules out the tempting alternative by explaining why qrtap_list_pages cannot serve this purpose.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key behavioral fact that an empty array means the code always resolves to its primary destination, and it warns about the destructive interaction with the sibling setter. It does not cover auth requirements or ordering, so it stops short of 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?

Three short sentences, front-loaded with the read operation, then the return-value semantics, then the sequencing warning. Every sentence adds actionable information 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?

For a single-parameter read with no output schema, the description covers purpose, return semantics (empty array), and sequencing risk, which is nearly everything an agent needs. Minor gaps like ordering or whether disabled rules are included keep 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 description coverage is 100% and the schema itself already disambiguates codeId (internal UUID vs. short_url slug), so the schema does the heavy lifting. The description only adds that a single code is targeted; baseline 3 applies when the schema fully documents the parameter.

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 ('Read') and a specific resource ('conditional (Smart Links) redirect rules currently set on one code'), with the scope narrowed to a single code. An agent can immediately distinguish this read-only inspection tool from the mutating sibling qrtap_set_smart_rules without inspecting 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?

Explicitly tells the agent when to call it: before qrtap_set_smart_rules, and states the consequence of skipping it ('you will silently drop rules you did not know about'). The alternative and the selection condition are both named, leaving nothing 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?

With no annotations, the description carries the full burden, and it delivers the most important behavioral fact: what the report contains (code count, combined total, per-day series, device split), which effectively substitutes for the missing output schema. It implies a safe read ('stats') but does not explicitly state read-only behavior or permission requirements; for a read-only aggregation tool this is a minor omission, not a gap.

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

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

Two tight sentences, front-loaded with the core purpose and followed by a clarifying use-case/alternative sentence. The illustrative examples ('all branches, all tables, all partner stickers') earn their place by making the batch scope concrete.

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?

Absent an output schema, the description compensates by enumerating the return contents (count, combined total, per-day series, device split), and all three params are schema-documented. Minor missing pieces remain: behavior when the group name is unknown/invalid, and whether from/to default to a specific window.

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

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

Schema description coverage is 100%, so all three parameters (group, from, to) are already fully documented in the schema, including the group enum values and ISO 8601 date semantics. The description adds conceptual context (the group defines the batch being aggregated) but no parameter-specific syntax or defaults beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource: aggregated scan statistics for a whole group of codes, and specifies exactly what the aggregate includes (code count, combined total, per-day series, device split). It distinguishes itself from per-code querying by saying it works 'without iterating over codes one by one', which implicitly contrasts with the single-code sibling qrtap_code_stats, though it never names that sibling.

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?

Explicitly frames the use case: 'the report for a batch — all branches, all tables, all partner stickers — without iterating over codes one by one', which tells the agent when to pick this over per-code stats. It stops short of naming qrtap_code_stats as the alternative or stating explicit exclusions (e.g., single-code lookup).

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

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

With no annotations, the description carries the full burden and does well: it discloses ordering (newest first), the returned fields, and an explicit PII constraint ('customers' names and phone numbers... do not copy it elsewhere'). It omits pagination/limits and any auth prerequisites, which keeps it just under 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?

The purpose and ordering are front-loaded, then filtering guidance, then the privacy caveat. Each sentence earns its place, though the PII sentence is somewhat verbose and could be tightened without losing meaning.

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, so the description correctly enumerates the return fields and the ordering, plus the PII handling rule. Pagination/result-size behavior is unstated, a minor gap for a list tool that could return many rows.

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 baseline is 3. The description adds meaning beyond the schema's 'Omit to list every request' by explaining that 'new' represents the actionable inbox and that omission is the everything-view — useful decision semantics rather than a restatement.

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 booking requests left by guests on the organization's public pages') plus ordering ('newest first') and the fields surfaced. It is clearly distinguishable from the sibling mutation qrtap_set_booking_status, so an agent can tell read-listing apart from status-writing without opening a 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?

Explicitly says 'status=new is the inbox that still needs a decision — that is the usual call' and 'Omit status to see everything,' which gives the default and the broad-scan condition. It stops short of naming sibling alternatives (e.g., set_booking_status for acting on a request), but the when-to-use guidance is 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?

With no annotations, the description carries the full burden and does much of it: it discloses result ordering ('newest first'), org-wide scoping, and the cost tradeoff of include_stats versus per-code stats calls. It does not state read-only nature explicitly or any auth/permission requirements, which is the remaining gap.

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

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

Three sentences, each front-loaded with a distinct purpose: identity/ordering, use cases, then filter and stats guidance. No filler; every clause carries actionable 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, and the description covers what comes back (codes with `id`, optional all-time non-bot scan counts). Pagination semantics live in the schema. Minor gaps remain around total counts and whether any codes are excluded, but an agent can 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: group filters 'a whole batch' while external_ref targets 'one specific code', and include_stats is framed as a batch-comparison shortcut. It clarifies the decision between the two filters beyond what the schema alone conveys.

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?

Opens with a specific verb+resource plus scope and ordering: 'List the organization's managed codes and short links, newest first.' It is clearly distinguishable from siblings like qrtap_list_pages and qrtap_list_bookings by naming the resource as codes/short 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?

Explicitly states two when-to-use cases ('find a code's id before retargeting it', 'check what already exists before creating more') and names a concrete alternative it is cheaper than: qrtap_code_stats. It also explains when to use group vs external_ref filters.

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

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

With no annotations, the description carries the behavioral burden and does disclose the listed template attributes, ordering, and the ownership/logo-image constraint. It does not mention pagination, rate limiting, or whether results are complete or truncated, so it stops short of full disclosure.

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 the operation and ordering, then the downstream purpose and creation constraint. Every sentence adds needed context and nothing is repeated from structured fields.

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 zero-parameter list tool with no output schema, the description covers what the templates contain and why an agent would call it. It leaves return-shape details such as pagination or whether all templates are returned unstated, which is a modest 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?

There are zero parameters, so the baseline is 4 and there is no parameter behavior to explain. The description correctly implies the tool takes no filtering input.

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 (list branded design templates) plus scope (organization-level) and ordering (newest first). Its stated purpose of obtaining a design_template_id distinguishes it clearly from write siblings such as qrtap_create_code and qrtap_create_codes_bulk.

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 says to use this only to get a design_template_id for qrtap_create_code or qrtap_create_codes_bulk. It also rules out creation through the server, explaining templates are created in the cabinet, which prevents an agent from looking for a create-template sibling.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that page content is excluded from the response and that only public (not draft-private?) organizational pages are listed, which shapes expectations. It omits volume, ordering, and pagination behavior, which is a real but modest gap for a zero-parameter read.

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 compact sentences, front-loaded with the verb and resource before the routing guidance. Every clause adds distinct value — the field list, the content exclusion, the sibling pointer, and the selection condition.

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 must describe results, and it does by naming the six returned fields plus the notable omission of content. Only lacking detail is result volume/ordering for an organization with many pages, which an agent might want before calling.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool applies, and the field enumeration helps frame what the results mean without overreach.

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 the organization's public pages' — and immediately enumerates the returned fields (slug, segment, theme, published state, version, public_url). It also explicitly distinguishes itself from qrtap_get_page and qrtap_create_page, so an agent can pick it 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?

Gives an explicit alternative ('use qrtap_get_page to read it') plus a positive selection condition: 'use this when you only need to discover the slug or check whether a page exists yet.' When-to-use and when-not-to-use are both stated outright.

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

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

With no annotations, the description carries full behavioral burden; it usefully discloses the publish workflow ('nothing a guest writes appears publicly until someone publishes it') and the default status bucket, but says nothing about permissions, pagination, or result volume. Genuine added context, but not a complete behavioral picture.

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 purpose then the default-behavior insight then the alternates. Every sentence adds information; nothing is redundant with the schema or title.

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-optional-enum list tool with no output schema and no annotations, the description covers what is listed, the default, and the meaning of alternates. Return shape and paging remain unspecified, which is the only meaningful 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 100% with an enum and per-value description, so baseline is 3. The description earns above baseline by translating 'pending' into the moderation-queue concept and pairing 'published'/'hidden' with the intent 'review earlier decisions', adding workflow meaning beyond the schema's short gloss.

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 guest reviews') plus scope ('left on the organization's public pages'), and frames the tool's question ('are there new reviews?') so an agent can distinguish this read operation from sibling moderation/mutation tools like qrtap_moderate_review.

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?

Explicitly explains that the default 'pending' is the moderation queue for finding new reviews, and that 'published'/'hidden' are for reviewing earlier decisions — clear when-to-use guidance for each value. It stops short of naming qrtap_moderate_review as the alternative when action (not listing) is needed.

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

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

With no annotations, the description carries the burden well: it discloses that the effect is immediate, publicly visible to everyone, made on behalf of the business owner, and requires prior user confirmation. It leaves out idempotency (calling hide on an already-hidden review) and error/permission behavior, which keeps it short of a 5.

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

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

Two sentences, the effect stated first and the confirmation requirement second. No filler and nothing important buried at the end.

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 two-parameter, no-output-schema tool this covers what matters: the visible consequence, the stake (acts for the business owner), and the required confirmation. A note on repeat calls or failure modes would make it 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 coverage is 100% and the enum already documents publish vs hide, so the baseline is 3. The description adds only marginal semantics ('immediately', 'visible to everyone') and says nothing about reviewId beyond what the schema states.

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 and resource: 'Publish or hide one guest review,' which immediately separates it from the read-only siblings like qrtap_list_reviews and the unrelated page/booking tools. The two possible effects are spelled out in the same sentence.

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 clear conditions for each action (publish = public immediately, hide = off the page) and an explicit procedural gate: show the review text and ask the user before calling. It does not name a sibling alternative for reversing a moderation decision, but for a binary-action tool the guidance is nearly complete.

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

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

With no annotations, the description carries the disclosure burden and does well: it states the real-person commitment, the absence of guest notification, and the irreversibility of moving back to 'new'. It still leaves out auth requirements and what happens on failure, so it is not exhaustive.

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 short and front-loaded: the action comes first, then the two things the user must be told, then the status constraint. Every sentence 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 two-parameter mutation with no annotations and no output schema, this covers the critical side effects and irreversibility. It is nearly complete, though it could say more about permissions or the result of confirmation.

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 both parameters are already documented there. The description reinforces that status is the business's own record and cannot return to 'new', but that constraint already appears in the schema and bookingId is not elaborated beyond its source tool.

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

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

The description opens with a specific verb pair and resource: confirm or decline one booking request. That is enough to separate it from listing, reviewing, or moderating siblings without opening a schema. No vague abstraction is used.

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 clear pre-call guidance: ask the user first because this is a commitment to a real person, and note that no guest notification is sent. It does not explicitly name an alternative tool or spell out when not to use this one, but the decision context is 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?

With no annotations, the description carries the full burden and does most of it: it discloses that the passed array wholesale replaces the existing set, that [] destroys all rules, that evaluation is top-to-bottom with first match winning, and that nothing matching falls back to the primary destination. It stops short of stating permission requirements, error behavior, or what a successful call returns.

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?

Every sentence earns its place: REPLACE is front-loaded, the semantics follow, then use cases, then the read-first instruction and clear behavior. No filler or redundancy despite reasonable length.

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

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

For a destructive batch-mutation tool with no annotations and no output schema, the description covers semantics, limits, ordering, and clearing behavior well. It could still say what the caller gets back on success or what happens on invalid conditions, but an agent has enough 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the replace-versus-merge semantics, the clearing behavior of an empty array, and the top-to-bottom evaluation order of the array. The 5-rule cap merely restates maxItems.

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 a specific verb (REPLACE) and resource (Smart Links rules of one code), then defines what those rules are: conditional redirects evaluated on every scan with first-match-wins and fallback to the primary destination. It is clearly distinguished from its read counterpart qrtap_get_smart_rules and from the simpler qrtap_change_destination.

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 states concrete when-to-use scenarios (iOS/Android app store routing, per-language pages, off-hours menu) and an explicit prerequisite: read the current set with qrtap_get_smart_rules before replacing it. The relationship to the alternative tool is spelled out rather than inferred.

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

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

With no annotations, the description carries the burden and does it well: it discloses that content is replaced wholesale with omitted fields erased, and that slug/public_url are immutable so printed QR codes stay valid. It does not state whether publishing is immediate/live, whether auth or ownership is required, or what confirming response comes back, which keeps it short of 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?

Three tight sentences: identity, consequence of immutability, then the destructive-replace warning with the remedy. The most dangerous fact is capitalised and placed before the recipe.

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 2-parameter mutation with no output schema, the definition covers identity, mutation semantics and correct usage pattern. The remaining gap is the return value and the meaning of 'new version' (numbering, rollback availability), which an agent calling it blind would want to know.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema lacks: it warns that `content` is a full replacement object rather than a patch, which changes how the agent must construct the parameter. It says nothing extra about `slug` beyond the schema, hence not 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 ('Publish a new version of an existing public page') plus the identifier ('by its slug'), which cleanly separates it from the sibling qrtap_create_page and from qrtap_get_page.

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?

Explicitly routes the agent to qrtap_get_page with a read-merge-write recipe for the partial-update case, and the framing of 'existing public page' implicitly excludes creation. The when and how are both spelled out.

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