QRStuff MCP Server

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful context that this creates a ticket in Zendesk, an external system, but it does not describe authentication needs, side effects, rate limits, or what happens after creation.

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, efficient sentence with no wasted words. The core action and resource are front-loaded.

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

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

With an output schema present and full schema description coverage, the description need not explain return values or all parameters. It gives enough context for a simple create tool, though it could more explicitly cover the required subject field or usage context.

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 the schema already documents all four parameters clearly. The description mentions name, email, and issue but omits subject, adding no meaning beyond what the schema provides.

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: 'Create a Zendesk support ticket.' It also names the primary customer identifiers and issue. However, it does not explicitly differentiate itself from siblings like search_knowledge_base, though those siblings are mostly unrelated QR-code tools.

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 provides no when-to-use guidance, no prerequisites, and no alternatives. It does not explain when to create a ticket versus searching the knowledge base or using another support pathway.

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=false, openWorldHint=true, and idempotentHint=false. The description adds only 'via the QRStuff API', which duplicates openWorldHint and provides no further behavioral context such as side effects, persistence, or return format. It does not disclose that dynamic QR codes are created by default or that the operation is non-idempotent.

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, front-loaded with the action and resource. It contains no filler or repetition. It is appropriately sized for the minimal information it conveys.

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

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

For a tool with a complex nested input object, no output schema, and many styling options, the description is far too sparse. It does not explain the required input structure, the dynamic/static distinction, or what the tool returns. An agent would need to rely entirely on the schema and annotations.

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 description provides no information about the single 'input' parameter or its nested fields. Although the schema documents the nested properties, the top-level parameter lacks a description and the context reports 0% schema description coverage, so the description fails to compensate. It does not explain required 'data', type defaults, or how to structure the input object.

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

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

The description states a specific verb 'Generate' and resource 'QR code', and the mention of the QRStuff API clarifies the mechanism. It does not explicitly differentiate from siblings like update_qr_code or get_qr_code_by_id, but the verb itself distinguishes creation from retrieval or update.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or which sibling tool to choose for related tasks. The description only states what it does, not when.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered by structured data. The description adds the backing endpoint path but no auth requirements, rate limits, or freshness/caching behavior. With annotations carrying the safety burden, this is an adequate but unremarkable addition.

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 that are front-loaded with the resource and its payload. The trailing "Uses GET /api/analytics/account-activity" adds little value for an agent and is arguably filler, but the overall size is lean.

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-value explanation is not required, and a zero-parameter read-only tool is low complexity. The description covers what the tool returns and its endpoint, leaving only sibling disambiguation 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond the schema, and it correctly implies the call requires no 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?

States a specific verb+resource ("Fetch account activity") and enumerates the data returned: dynamic QR usage, monthly scan limits, scans this month. That is clear enough to know what it does, but it does not distinguish itself from siblings like get_account_overview or get_account_scans, which sound like they may return overlapping analytics.

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?

There is no when-to-use guidance and no alternatives named. With several closely-named siblings (get_account_overview, get_account_scans, get_subscription_detail), the agent is left to guess which of these to call. Only implicit context is provided via the listed return fields.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds no behavior on top: no auth requirements, rate limits, or freshness. Behaviorally transparent by omission only because the annotations carry 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 lines, metric list front-loaded, and the endpoint path tacked on at the end. Nothing 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?

For a zero-parameter read-only tool with an output schema and complete annotation coverage, the description is adequate. The output schema covers the return shape, so the description needn't explain it.

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?

Zero parameters, so the baseline is 4. No parameter semantics are needed and none are missing.

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 (Fetch) and resource (account-level analytics overview) and enumerates the returned metrics. It does not distinguish itself from the many sibling scan-analytics tools (get_account_scans, get_total_scans, etc.), so it falls short of 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?

The word 'overview' implies a summary-level call, contrasting implicitly with the granular scan tools, but no explicit when-to-use or when-not-to-use guidance or alternatives are named. Usage is only implied.

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 establish readOnly, idempotent, non-destructive and openWorld behavior, so the safety profile is covered. The description adds that results are paginated and that the underlying call is a POST to /api/account/scans, which is modest extra context, but the default-range sentence merely duplicates the start_date/end_date schema descriptions.

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, front-loaded with the action and scope, with no filler. The endpoint detail is of marginal value, but nothing is padded or buried.

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 100% parameter coverage means the only job left is orientation, which the scope and default-range statements provide. An agent can call it correctly, though it lacks guidance on paging limits and on the overlap with the by-date/by-region/by-device siblings.

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 eight parameters (including the group_by enum and the conditional country requirement) are already documented, making the baseline of 3 appropriate. The description only echoes 'optional group_by' and the date default, adding no syntax or interaction detail 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 (Fetch) and resource (paginated scan data) with an explicit scope qualifier, 'for the whole account', which implicitly separates it from get_project_scans and get_qrcode_scans in the sibling list. However, it never names those alternatives, so the differentiation is inferred rather than stated.

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?

'For the whole account' implies when this tool is preferable to the project- or qrcode-scoped scan tools, and the default 30-day window is given. There is no explicit when-to-use/when-not-to-use statement or mention of the many aggregation siblings (get_scans_by_date, get_scans_by_region, etc.) that overlap with this tool's group_by option.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds genuinely new behavior — that results are paginated one page at a time and that an omitted range silently defaults to the last 30 days. That defaulting behavior is important and not stated 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?

Three short sentences, front-loaded with the core action and followed by the two facts an agent actually needs (pagination, default range). The raw endpoint path adds little but costs little.

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 read-only paginated list tool with full schema coverage and annotations covering the safety profile, the description supplies the remaining essentials: pagination semantics and default date behavior. No output schema exists, but the return shape is adequately implied by 'one page at a time'.

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 the schema already carries the parameter burden, including the REQUIRED-when-dates-mentioned caveat on start/end date. The description restates the default range but adds no format or pagination-limit detail beyond the schema, so 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 — fetching paginated scan logs — and scopes it to a project, which separates it in kind from account- and qrcode-level scan tools. It does not, however, name or contrast those siblings explicitly, so the agent must infer the resource hierarchy.

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?

Scope ('for a project') implies when to use it versus get_account_scans or get_scans_by_date, but there is no explicit when-to-use/when-not-to-use guidance and no mention of the alternative scan tools. The default date-range note is the only actionable usage context provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds essentially nothing beyond that — 'full details' is not a behavior, it is a vague scope claim, and there is no mention of what is returned or error behavior for an unknown id.

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 short sentence with the lookup key front-loaded and zero filler. Nothing could be removed without losing content, and nothing important is buried.

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 is the only place the return surface could be characterized, and 'full details' leaves the actual payload undefined. For a simple single-parameter read the annotations and schema carry the calling mechanics, so it is minimally viable but not complete.

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

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

Schema description coverage is 100% with a single well-described parameter ('ID of the QR code to fetch'), so the schema does the heavy lifting. The description's 'by id' merely mirrors that, adding no id format, source, or validity information.

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 (fetch), resource (QR code), lookup key (by id), and scope ('full details'), which is clear enough to separate it from list_qrcodes. However, it never names the sibling tools it sits next to (get_qrcode_history, get_qrcode_scans), so the differentiation is left to inference.

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?

There is no when-to-use guidance at all. With siblings like list_qrcodes, get_qrcode_history, get_qrcode_scans, and update_qr_code, an agent gets no signal about when this lookup is the right choice versus those alternatives, nor any prerequisite (e.g., needing an id obtained from a list call).

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds value beyond that by naming the underlying call (GET /api/qrcodes/{idqrcode}/history) and disclosing cursor-based pagination, which is genuine behavioral context not present 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 tight sentences with the core purpose front-loaded and the transport/pagination detail following. Every clause earns its place; nothing is redundant.

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 not be explained, and annotations carry the safety profile while the schema carries all four parameters. For a read-only audit-fetch tool the definition is complete enough to invoke 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%, so each parameter (action, cursor, idqrcode, per_page) is already self-documented in the schema. The description only alludes to the cursor mechanism and adds no field-level meaning beyond the schema, which is the baseline-3 case.

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 ('Fetch audit history for a QR code') and parenthetically enumerates the event types covered (created, updated, deleted). It is clearly distinguishable from read siblings like get_qr_code_by_id and get_qrcode_scans, though it never names those alternatives explicitly.

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 word 'audit history' implies when to reach for this over scan-analytics tools such as get_qrcode_scans or get_account_activity, but there is no explicit when-to-use/when-not statement or prerequisite (e.g. permissions) called out. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: results are paginated one page at a time and the queried endpoint is POST-based, plus the default date window. It stops short of describing page-iteration or rate-limit behavior.

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

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

Three short, front-loaded sentences that lead with the core action and then layer in endpoint, pagination, and default range. No filler, though the endpoint path is arguably low-value detail for an agent choosing a tool.

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 carries some burden for describing what comes back, but it says only 'one page at a time' and never lists returned fields or how to advance pages. Safety behavior and parameters are adequately covered by annotations and a 100%-documented schema, so the remaining gap is moderate rather than severe.

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%, with start_date/end_date/page/per_page all documented in the schema itself, so the baseline is 3. The description restates the default 30-day-to-today range that the schema already specifies, adding no format or edge-case detail beyond 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 states a specific verb and resource ('Fetch paginated scan logs for a QR code') and scopes it to a single QR code ID, which is clearer than a generic 'get scans'. However, it never distinguishes itself from the many sibling scan tools (get_account_scans, get_project_scans, get_scans_by_date, get_total_scans), so an agent cannot route between them from the text alone.

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 useful operating context — one page at a time, default window of last 30 days to today — which implies when the tool applies. But there is no explicit when-to-use vs. when-not guidance and no mention of the sibling alternatives that cover other scan scopes (account, project, country, device).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds the default date range and the POST-with-group_by implementation detail, which is useful context, but doesn't disclose pagination behavior or return shape beyond what the output schema covers.

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

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

Three short sentences, front-loaded with the core purpose, followed by the mechanism and the scope-specific requirement. No filler text.

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 read-only annotations and the presence of an output schema, the description covers what an agent needs: grouped-by-country output, default range, and scope-specific parameter requirements. It could mention pagination defaults or how scope affects which IDs are required, but is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including enum values and REQUIRED conditions. The description only confirms the idqrcode requirement for scope=qrcode, adding little beyond the schema's baseline.

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 (Fetch) and resource (scan counts grouped by country), and names the three scopes. It is clearly distinguishable from siblings like get_scans_by_device or get_scans_by_region by the grouping dimension.

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 explains the scoping requirement ('For scope=qrcode only idqrcode is required') and indicates the default range, giving clear context for use. It doesn't explicitly name alternatives like get_scans_by_date or get_total_scans, so no full 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered externally. The description adds useful context (last-30-days default, POST-based group_by=date endpoint) but says nothing about result ordering, pagination interplay, or what happens when only one date bound is supplied.

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 purpose, followed by the endpoint/default rationale and the scope requirement. No filler; the only borderline sentence is the implementation note about POST/group_by, which is still informative for prediction of behavior.

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 annotations carry the read-only/idempotent profile. The description covers the default window and the key conditional requirement, leaving only minor gaps around date-range edge cases and pagination behavior that the schema partially addresses.

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 the schema already documents all seven parameters, making 3 the baseline. The note 'for scope=qrcode only idqrcode is required' adds a conditional nuance, but it sits in tension with the schema's idproject description ('Required when scope=project or qrcode'), so the net added value is limited.

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 ('Fetch scan counts grouped by date') and names the three scopes it serves, which distinguishes it from the sibling grouping tools like get_scans_by_country/device/region. It does not, however, distinguish itself from get_account_scans / get_project_scans / get_qrcode_scans, which fetch scans at the same scopes without date grouping.

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 scope enum (account/project/qrcode) and the 'default date range: last 30 days' establish the operating context, and the final sentence implies usage for the qrcode scope. There is no explicit when-to-use guidance versus the numerous scan-related siblings, so the agent must infer selection from the scope argument alone.

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 establish readOnly/idempotent/non-destructive/openWorld, so the bar is lower, and the description still adds non-obvious behavior: the read is executed through POST scans endpoints with group_by=device, plus the 30-day default window. It does not mention pagination behavior despite exposing page/per_page, but the added endpoint and default-range details are substantive.

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 action and grouping, followed by implementation and default-range notes. No filler, though the endpoint detail is marginally less important than the scope rules it follows.

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 not be explained, and annotations carry the safety profile. Scope rules, date defaults, and the required-id condition are all present; only the idproject/idqrcode requirement discrepancy leaves 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?

Schema description coverage is 100%, so baseline is 3; the schema already documents every parameter including the date requirements. The description adds one dependency clarification ('for scope=qrcode only idqrcode is required'), though that statement sits in tension with the schema's idproject note claiming it is required for scope=qrcode as well.

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 (fetch), resource (scan counts), and grouping dimension (device platform), with the supported scopes spelled out. The grouping dimension implicitly separates it from siblings like get_scans_by_country or get_scans_by_date, but no sibling is named explicitly, so routing relies on the agent noticing the 'device' axis.

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 useful defaults ('Default date range: last 30 days') and a conditional requirement ('For scope=qrcode only idqrcode is required'), which is genuine usage context. However, it never says when to choose this tool over get_account_scans, get_project_scans, get_qrcode_scans, or the other group_by variants, so the choice is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: the underlying transport ('Uses POST scans endpoints with group_by=region') despite being a read operation, and the default date-range window.

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 primary purpose before defaults and conditional requirements. No filler; each sentence carries distinct information.

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

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

With an output schema present, the description needn't explain return values, and it covers purpose, scope, date defaults, and conditional parameter rules. Minor gaps remain around the 'region' filter semantics and pagination, but nothing an agent needs to call it 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 description coverage is 100%, so every parameter including conditional requirements is already documented in the schema. The description's notes on scope and default range largely restate that. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Fetch scan counts grouped by region within a country') plus the three scopes it supports. This clearly distinguishes it from siblings like get_scans_by_country, get_scans_by_date, and get_scans_by_device without the agent needing to open schemas.

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 practical context on defaults ('last 30 days') and the conditional requirement ('For scope=qrcode only idqrcode is required'), which helps invocation. However, it never states when to prefer this over get_scans_by_country or get_scans_by_device, so the routing decision is left implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the provider (QRStuff API) and the return contents, but says nothing about authentication requirements, rate limits, or behavior when the user has no subscription.

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

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

Two tight sentences with the action front-loaded and no filler. The enumerated return fields are mildly redundant with the output schema but remain short and scannable.

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

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

A zero-parameter read of a single resource, with an output schema that already documents the return shape and annotations that cover safety. The description supplies everything else an agent needs to call it correctly; only the missing sibling differentiation and auth context hold it back.

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 and the baseline for an empty schema applies. No misleading parameter language is present.

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: it fetches the current user's subscription detail. An agent immediately knows what comes back. It does not, however, distinguish itself from nearby siblings such as get_user_profile or get_account_overview, which an agent might reasonably confuse for subscription/account data.

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

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

Usage is implied by the purpose — call it when subscription state is needed — but there is no explicit when-to-use statement, no prerequisites, and no routing away from get_account_overview or get_user_profile. Adequate but with a real gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds no behavioral context beyond that — nothing about what 'top-performing' means, how results are ranked, or how date defaults behave (that detail lives only in the schema).

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

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

A single front-loaded sentence with the verb and resource first and zero filler. Nothing needs trimming and nothing relevant is padded in.

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?

Output schema exists, so return values need no explanation, and annotations plus full schema coverage carry the safety and parameter burden. However, for a tool whose main risk is confusion with sibling analytics tools, the absence of any disambiguation leaves a real 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 description coverage is 100%; the schema fully documents scope, date ranges, and the idproject/idqrcode dependencies. The description adds no parameter 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 concrete verb (Fetch) and a specific resource (top-performing date analytics) with the three supported scopes (account, project, QR code). The 'date' dimension implicitly separates it from get_top_performing_location and get_top_scanner, though it never names those siblings explicitly.

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?

Contains no when-to-use, when-not-to-use, or alternative guidance. The near-identical siblings get_top_performing_location and get_top_scanner, plus get_scans_by_date, are never referenced, so an agent must infer selection from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond that: it never says how many locations are returned, how 'top-performing' is ranked (scans? unique users? over what window?), or how results are ordered, which is the kind of context this tool actually needs.

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

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

A single front-loaded sentence with no filler or redundancy. It is appropriately sized, though at one clause it carries no extra operational 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?

An output schema exists, so return values need not be explained, and all five parameters are documented in the schema with conditional requirements spelled out. The tool's scope combination logic (idproject shared between project and qrcode) is covered by the schema, leaving only ranking/result-size semantics 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 schema descriptions are unusually rich, including the conditional requirement that idqrcode is needed when scope=qrcode and the date-omission rules for start_date/end_date. The description adds no parameter detail beyond the schema, so the baseline 3 is correct.

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 (fetch) plus resource (top-performing location analytics) with the three supported scopes named, which lets an agent distinguish it from generic scan-listing siblings like get_scans_by_date. It does not, however, differentiate itself from closely related siblings such as get_scans_by_country or get_scans_by_region, which also return geographic performance data.

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?

Enumerating the account/project/qrcode scopes implies when the tool applies, but there is no explicit guidance on when to choose this over get_scans_by_country, get_scans_by_region, or get_top_performing_date. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered externally. The description adds only the account/project scope framing and nothing about aggregation window or ranking behavior; with annotations carrying the load, this is adequate but not additive.

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 short sentence with no waste and the resource front-loaded. It is appropriately sized, though brevity here partly reflects a lack of content rather than disciplined editing.

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 not be explained, and annotations cover the safety profile. Still missing is any indication of what 'top scanner' ranks by or how the account/project results differ, leaving the agent to infer the analytic dimension.

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 carries the important detail (date range requirements, project ID requirement, and the note that qrcode scope is unsupported). The description adds no parameter syntax or format beyond what the schema already states, so 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 ('Fetch'), a specific resource ('top-scanner QR code analytics'), and the scope dimension ('account or project'). It is reasonably distinguishable from siblings like get_top_performing_location, though the term 'top-scanner' is left slightly ambiguous as to which dimension is ranked.

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

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

The description gives no when-to-use guidance, no exclusions, and does not name any alternative for retrieving scan breakdowns (e.g. get_top_performing_location, get_scans_by_device). The 'account or project' phrase hints at a usage decision but that is already fully expressed by the scope parameter.

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 establish the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds nothing about response shape or aggregation behavior, but with annotations covering safety and an output schema present, this is acceptable context.

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 efficient sentence that front-loads the verb and resource. No waste, though it could be tighter by naming the alternative tools rather than just listing scopes.

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 handling return values and annotations covering safety, the description is functionally adequate. However, for a tool with five optional parameters where scope drives which IDs are required, the description should clarify how scope selection works and how it relates to the granular sibling tools.

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 the schema already documents all five parameters including enums, defaults, and required conditions. The description adds marginal value by naming the three usable scopes, but the schema does the heavy lifting. Baseline elevated slightly by the scoping hint.

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 clear verb ('Fetch') and resource ('total scans analytics') with scope modifiers (account, project, QR code). However, it does not distinguish this aggregate 'total' tool from siblings like get_account_scans, get_project_scans, and get_qrcode_scans, which appear to cover the same scopes at a more granular level.

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?

No guidance on when to use this tool versus the numerous sibling scan tools (get_account_scans, get_project_scans, get_qrcode_scans, get_scans_by_date, etc.). The description implies the scopes but leaves the agent to infer which tool to pick from a crowded family of scan-related siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is fully covered. The description adds only that the link is for customer feedback, not whether the URL is static, per-account, or region-specific, so it contributes little beyond structured data.

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

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

A single front-loaded sentence with no filler. Every clause earns its place given how little this tool needs to convey.

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-value explanation is unnecessary, and the annotation set covers the safety profile. For a zero-parameter URL getter this is fully sufficient to call 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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the empty object is self-explanatory.

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

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

States a specific verb (Return) and resource (Trustpilot review URL), with a brief note on what the URL is for. It is unambiguous against the sibling list, none of which touch Trustpilot, though it adds no scope detail such as whose account the link belongs to.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. The agent can infer intent from the name, but the description provides no routing information.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety and idempotency profile is fully covered by structured data. The description adds nothing behavioral beyond that – no note on aggregation window, how a unique user is counted, or data freshness. With annotations carrying the burden, a 3 is appropriate.

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

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

A single front-loaded sentence with no filler, and the scope options are surfaced immediately. It is efficient, though it is arguably a touch sparse for an analytics tool with five parameters.

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 not be described, and annotations cover the safety profile; the schema covers all five parameters at 100%. What remains is the description stating the metric and scope, which it does. The one residual ambiguity – whether 'unique users' and 'unique scans' are synonymous – keeps it just short of 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%, so the schema already documents scope, dates and the idproject/idqrcode dependencies. The description only restates the scope choices, adding no format, default or dependency semantics beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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?

Names a specific verb (Fetch) and resource (unique users / unique scans analytics) and enumerates the three scopes it operates over. This implicitly separates it from siblings like get_total_scans or get_account_scans by naming the 'unique' metric. It stops short of explicitly naming an alternative tool, so it is clear but not fully sibling-differentiated.

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 through the scope parameter (account/project/qrcode) and the tool name. There is no explicit statement of when an agent should prefer unique-user counts over total scans, nor any exclusions or prerequisites. This is minimum-viable guidance rather than genuine when-to-use direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds only 'via the QRStuff API,' which is implementation detail rather than meaningful behavioral context such as auth requirements or rate 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?

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for a simple zero-parameter read tool.

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 current-user profile fetch, the description is mostly complete: it says what is fetched and that an output schema exists to explain return values. It could mention authentication or account context, but the annotations and output schema cover most remaining needs.

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, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and no additional parameter meaning is needed.

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: fetch the current user's profile. It is clear what the tool returns, though it does not explicitly distinguish itself from sibling account-related tools like get_account_overview.

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 no when-to-use guidance, prerequisites, or alternatives. The purpose implies usage, but the description gives no explicit context for selecting this tool over sibling account/profile tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the account-scoping detail and says nothing about pagination, ordering, or how long deleted projects remain listable — useful context that is absent.

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

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

A single front-loaded sentence with no filler; the resource and scope appear immediately. Nothing could be trimmed without losing 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?

For a zero-parameter read tool with rich annotations and a trivial schema, the description is nearly sufficient. The only gap is that with no output schema the agent does not learn what a deleted project record contains or whether results are paginated.

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 per the rubric the baseline is 4. There is nothing for the description to clarify, and it correctly does not invent parameter behavior.

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 (List) and resource (deleted projects) plus scope (current user's account), so an agent can distinguish it from list_projects. It never names the sibling it contrasts with, however, so differentiation is left to inference from the name.

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

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

The word 'deleted' implicitly tells the agent to use this when it needs soft-deleted projects rather than active ones, but there is no explicit when-to-use statement and no mention of the relevant alternatives (list_projects, restore_deleted_project).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive semantics, so the safety profile is covered. The description adds genuinely useful extra context beyond that: the underlying GET /api/projects call and the pagination behavior ('Returns one page at a time'), which tells the agent results must be paged through.

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 with no redundancy, front-loaded with the core purpose. The endpoint and pagination notes each earn their 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 read-only list tool with annotations covering safety and no output schema, the description gives enough to invoke it correctly and flags pagination. It could say more about the shape of a returned page, but the low-risk read nature keeps this adequate.

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 the schema already documents every parameter, including the enum and range. The description only restates search, pagination, and sorting at a high level without adding format or syntax detail, 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?

The description names a specific verb and resource ('List active projects') and scopes it with 'active', which implicitly separates it from the sibling list_deleted_projects. It never explicitly names that sibling, so it stops short of a 5, but an agent can still tell the two apart.

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 implies when the tool is used (list + optional search/pagination/sorting) but offers no explicit when-to-use vs when-not guidance and never routes the agent to alternatives such as list_deleted_projects. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful routing context about which endpoint is hit, but omits pagination behavior and return shape despite paginated params.

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 lead sentence plus three tight bullets, front-loaded with the core purpose and branching logic. No filler sentences.

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?

Adequate for a read-only list tool whose annotations cover safety and whose params are fully schema-documented. Minor gap: no mention of pagination behavior or response format, though no output schema exists.

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 six params are already documented. The description clarifies the interaction between idproject and q, which is additive but minimal over the schema baseline.

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 (List) and resource (QR codes) with explicit scope. Distinguishes from siblings like get_qr_code_by_id (single fetch) and generate_qr_code (creation) by its 'list' semantics.

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?

Explains the two optional filters and their combined effect, effectively telling the agent when to provide idproject vs q. Does not name an alternative sibling for cross-project listing, but the branching behavior is clearly described.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive operation with open-world scope, so the safety profile is covered. The description adds only the vague phrase 'under the user's account' and says nothing about required ownership of both projects, reversibility, or side effects on scans/history.

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 efficient sentence with the action front-loaded and no filler. It is appropriately sized but arguably under-specified rather than genuinely concise.

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, but the description leaves the central ambiguity with 'transfer_qrcode' unresolved for a mutation tool. Given the cluttered sibling namespace, it is not complete enough to guide correct selection.

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

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

Schema description coverage is 100%, and both parameters (idqrcode, idproject) are documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or constraint detail beyond what the schema already provides.

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 ('Move a QR code') plus the scope ('from one project to another under the user's account'), so the core operation is unambiguous. However, it offers no differentiation from the sibling 'transfer_qrcode', which sounds like the same operation, so an agent cannot tell them apart from the text alone.

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?

There is no explicit when-to-use guidance and no mention of alternatives. With a sibling named 'transfer_qrcode' that plausibly covers the same action, the omission is a real gap – the agent has no basis for choosing between the two.

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 non-read-only, idempotent, non-destructive, open-world semantics, so the safety profile is covered. The description adds a real behavioral detail not in the annotations: restoration targets the current user's account, not the original owner. It omits what happens to child QR codes associated with the project, which is material for a restore operation.

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 short, front-loaded sentence with no filler. It is appropriately sized, though it errs toward under-specification rather than tightness for a mutation tool.

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 not be explained, and the sole parameter is documented. However, for a state-changing restore the description should at least note the deleted-state prerequisite and the account-scoping side effect on associated QR codes.

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 single idproject parameter is fully documented in the schema as the ID of the deleted project. The description adds nothing beyond that, so the baseline 3 applies.

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

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

Names a specific verb (restore) and resource (deleted project), so it is instantly distinguishable from siblings like restore_deleted_qrcode and list_deleted_projects. It does not explicitly name those alternatives, so it falls short of full sibling differentiation.

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?

There is no when-to-use guidance, no prerequisite stating the project must already be in a deleted state, and no pointer to list_deleted_projects as the way to obtain a valid idproject. Usage is only inferable from the tool 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation profile and repeat-safety are covered structurally. The description adds only the target scope ("current user's account"), with no mention of required permissions, failure modes, or what happens if the QR code was already restored.

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, the core action first and the input constraint second. Nothing is redundant or padded.

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 not be explained, annotations carry the safety and idempotency profile, and the description covers the one non-obvious input requirement. Nothing essential for a correct call 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% and both params are optional with defaults, so the schema alone would not reveal that at least one is mandatory. The description's "Either idqrcode or shorturl_key must be provided" supplies that constraint, which is genuine added meaning above the baseline.

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 ("Restore a deleted QR code") plus the scope ("to the current user's account"), which an agent can act on directly. It does not differentiate itself from the sibling restore_deleted_project, but the resource is unambiguous.

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 usage context is implied by the name and the "deleted" qualifier, but there is no explicit when-to-use framing and no mention of the sibling restore_deleted_project or the list_deleted_projects prerequisite. The second sentence is input guidance rather than use-case 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that – no rate limits, no scope or freshness of the knowledge base, no indication of result quality or fallback behavior.

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

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

A single efficient sentence that front-loads the verb and resource. Slightly awkward phrasing ('against user query') but no wasted text.

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 (one param) and has an output schema, so return values need not be explained, which lowers the bar. Still, for a conversational retrieval tool the description gives no guidance on when it should be preferred over asking the user or using another tool, leaving 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 is a single required parameter with 100% schema description coverage, so the schema already documents 'query'. The description adds no syntax, format, or query-construction guidance 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: 'Search the QRStuff knowledge base for relevant information.' An agent can tell this is a retrieval tool over a knowledge base, distinct from the many QR-code/account siblings. It does not, however, name or contrast any specific sibling tool.

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?

No when-to-use, when-not-to-use, or alternative routing is provided. It's implied that you call this when you need knowledge-base information, but nothing tells the agent how this differs from e.g. create_support_ticket or the account/scan tools for answering user questions.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds real operational context beyond them: the subscription prerequisite and the pre-existing anonymity of the code. It leaves the ownership/state change after transfer unstated.

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 action and scope, followed by the selection constraint and the prerequisite. No redundant or filler text.

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 not be explained, and the prerequisites and parameter selection are covered. Slightly incomplete on what happens to the original anonymous ownership and how it interacts with move_qrcode_to_project.

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. The description adds the constraint that at least one of idqrcode or shorturl_key must be present, which the schema does not enforce (both default to empty/0), genuinely increasing value over the structured fields.

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 (transfer) and resource (QR code) with clear scope: 'anonymously created' QR code moved to 'the current user's account'. This is distinguishable from siblings like move_qrcode_to_project or update_qr_code, which operate on already-owned 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?

Gives a clear precondition ('Requires active paid subscription') and an alternative-selection rule ('Either idqrcode or shorturl_key must be provided'), but does not contrast with siblings such as move_qrcode_to_project or explain when not to use it.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: the content-vs-styling partial-update rule and the fact that updated details come back on success. It does not mention permission requirements, whether unspecified fields are preserved or cleared, or the null-removal behavior documented only in the schema.

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

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

Three short sentences with the core action front-loaded and the conditional update rule immediately after. No filler, though the final 'returns updated details' sentence is thin given there is no output schema to describe.

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 over a large nested object, the definition covers the essential partial-update semantics and the success outcome, and annotations cover safety/idempotency. It leaves gaps around what happens to omitted fields, null-based removal of logo/gradient/background image, and whether the caller needs auth or ownership of the QR code.

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?

Top-level schema description coverage is reported as 0%, but the nested 'input' object documents ~24 properties in detail, so the schema carries most of the load. The description only groups them into 'content' and 'styling' categories without adding format, enum, or default semantics — useful framing, but no new parameter-level information.

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 (update ... an existing QR code) and scopes it to content and/or styling, which is enough to separate it from generate_qr_code and get_qr_code_by_id. It stops short of naming a sibling or an explicit boundary, so it is clear but not maximally differentiated.

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 usage via one behavioral condition ('If content fields are not provided, only styling is updated'), which tells the agent a partial update is legal. It offers no when-to-use vs. alternatives guidance, no prerequisites, and no note on when to prefer generate_qr_code or move_qrcode_to_project.

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=false, idempotentHint=false, and openWorldHint=true, so the mutation/non-idempotent profile is covered structurally. The description adds the return field name (idfs_file), which is useful, but says nothing about size limits, allowed MIME types, failure modes, or rate 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?

A single front-loaded sentence with zero filler, but it is so terse that it borders on under-specification rather than maximal efficiency.

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 not be described, and annotations carry the safety profile. For a 2-parameter tool the description is nearly sufficient; only the missing usage context (what consumes idfs_file) keeps it from being complete.

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

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

Schema description coverage is 100% with only two required parameters (base64_data, mime_type), so the schema fully documents them. The description adds the conceptual link that this is a file upload returning an idfs_file, but no format or constraint detail 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?

The description gives a specific verb and resource ('Upload a file to QRStuff API') and names the returned identifier ('idfs_file'). No sibling performs uploads, so the purpose is unambiguous, though it does not explicitly contrast with any 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?

There is no when-to-use guidance, no prerequisite (e.g. authentication, required prior steps), and no mention of the downstream tool that consumes the returned idfs_file. Usage is only implied by the verb.

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