Quality QR

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

With no annotations provided, the description carries the full burden. It transparently discloses the return payload: 'total scans, scans by day, device breakdown (mobile/tablet/desktop), and top 5 countries.' It also implies read-only behavior by context. It does not mention any side effects or error conditions, but for a read-only analytics query, this is adequate.

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

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

The description is three concise sentences: purpose, usage trigger, and return summary. It is front-loaded with the main verb and resource, and every sentence adds value without fluff or redundancy.

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

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

For a simple query tool with two parameters and no output schema, the description provides complete context: what it does, when to use it, and what it returns. The schema covers parameter semantics, and the tool has no complex edge cases or side effects requiring further elaboration.

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 minimal meaning beyond the schema: it implies days from 'daily scan trends', but the schema already fully describes id and days parameters. There is no additional context like parameter relationships or format details.

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

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

The description clearly states it retrieves scan analytics for a specific QR code, with a specific verb ('Get') and resource ('scan analytics'). It distinguishes itself from siblings like quality_qr_get or quality_qr_list by detailing specific analytics metrics (total scans, daily trends, devices, countries), making the purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'when the user wants to know how many times a QR code has been scanned, see daily scan trends...' This provides clear context. However, it does not explicitly mention when not to use it or name alternative tools for non-analytics queries, so it misses the full when/when-not/alternatives criterion.

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

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

With no annotations, the description carries full disclosure burden. It states that the QR code is 'trackable', 'saved to your account', 'persisted with scan tracking and analytics', and 'Returns an inline SVG image'. This adds valuable behavioral context beyond the schema, though it omits potential side effects or required authentication.

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 three sentences, each earning its place: purpose, usage scenario, and key behavior/return. It is front-loaded and free of fluff or redundancy.

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

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

Given six parameters with nested objects and no output schema, the description covers the essential aspects: what it does, when to use it, persistence, tracking, and return format. It does not explain the 'data' vs 'content' split, but the schema does, so the description is sufficiently complete for tool 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%, so the baseline is 3. The description does not add parameter-level detail beyond what the schema already provides; it merely lists supported types in prose. The schema's thorough descriptions of 'data', 'content', 'isDynamic', and 'design' carry the semantic weight.

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

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

The description opens with a specific verb and resource: 'Create a new trackable QR code saved to your Quality QR account.' It clearly distinguishes this as the creation tool among siblings like list, get, update, delete, and analytics, and enumerates the supported content types.

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 explicit 'Use this when...' guidance listing many use cases (URL, WiFi, contact card, calendar event, phone, email, SMS, menu, app link, social profile). It does not explicitly state when not to use it or name alternatives, but the context is clear enough for a creation tool.

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

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

With no annotations provided, the description carries the full burden of disclosure. It discloses that deletion is permanent ('cannot be undone'), the immediate effect on the short URL ('immediately stop redirecting'), and the effect on plan quota ('frees up a plan quota slot'). This is robust behavioral transparency for a destructive action.

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 three sentences, each serving a distinct purpose: defining the action, specifying usage, and disclosing consequences. No redundant or verbose content.

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 delete tool with one parameter and no output schema, the description covers purpose, usage, and all critical behavioral effects. No access to return values is needed, and the tool's scope is fully explained.

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 input schema has 100% coverage for the single parameter 'id', including a description of its origin. The tool description adds no additional parameter semantics, but since the schema already fully documents the parameter, a baseline of 3 is appropriate.

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

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

The description clearly states the action ('Permanently delete a QR code'), the resource ('QR code'), and the scope ('from the user's account'). It distinguishes itself from sibling tools like quality_qr_update and quality_qr_get by emphasizing the permanent removal aspect.

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

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

Provides explicit usage context: 'Use this when the user wants to remove a QR code they no longer need.' It doesn't explicitly mention alternatives or when not to use, but the context is clear and sufficient for a delete operation.

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?

There are no annotations, so the description carries the full burden. It discloses the tool's behavior by stating it 'Returns all metadata including content, destination, design, scan limits, and timestamps,' giving insight into the response contents. It implicitly indicates a read-only operation via 'Get,' but does not detail potential errors or auth requirements. The return-value disclosure is strong enough for a read tool.

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

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

The description is three sentences: the first states the purpose, the second gives usage guidance, and the third describes return contents. Every sentence adds value and is front-loaded with the core action. There is no fluff or repetition.

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

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

For a simple get-by-ID tool with one parameter and no output schema, the description sufficiently covers what the tool returns and when to use it. It mentions specific metadata fields (destination, design, scan limits, timestamps) that help the agent anticipate the response. It does not discuss error handling or permissions, but these are not critical for a read tool and are not required by the output schema absence.

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

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

The schema description for the 'id' parameter already explains how to obtain it ('Obtain this from quality_qr_list or quality_qr_create responses'), which is clear and thorough. The tool description adds no further parameter semantics beyond the schema, but since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Get full details of a specific QR code by its ID.' It uses a specific verb ('Get') and resource ('QR code'), and distinguishes itself from siblings like quality_qr_list (which lists all) and quality_qr_update (which modifies) by focusing on inspecting a single QR code's configuration, destination, design, and status.

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 explicit usage context: 'Use this when the user wants to inspect a particular QR code's configuration, check its destination URL, view its design settings, or see its current status.' This clearly states when to use the tool, though it doesn't explicitly mention when not to use it or name alternatives. The context is sufficient for an agent to choose this over listing or updating.

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

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

No annotations are provided, so the description carries full burden. It adds useful return-field details (ID, name, type, short URL, active status, creation date) but omits ordering, pagination behavior beyond schema defaults, or read-only confirmation. It does not contradict any annotation.

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

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

Two sentences, front-loaded with 'List QR codes', and each sentence carries meaningful content. No fluff or redundancy; efficient and well-structured.

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 list tool with no output schema, the description adequately covers return fields and usage context. It could mention response ordering or total count, but the simple tool and schema details make this sufficiently complete for an agent.

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 description adds no extra parameter semantics beyond what the schema already documents (type filter, limit, offset). It does not repeat or expand on them, but the baseline holds.

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

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

The description clearly states the tool lists QR codes in the user's Quality QR account, with a specific verb and resource. It differentiates from sibling tools like quality_qr_get (single retrieval) by emphasizing the list operation and enumerating returned fields.

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

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

Provides explicit 'when to use' guidance: to see existing codes, find a specific code, or check count. It lacks when-not/alternative recommendations (e.g., for a single code use quality_qr_get), but the context is clear and enough for most agents.

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

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

With no annotations, the description carries full burden. It discloses that destination URL changes only work for dynamic types and that the physical QR code doesn't need reprinting. It also notes that isActive=false stops redirects (though this is also in schema). It could mention error behavior for invalid updates, but it covers the key operational nuances.

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

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

Two sentences, front-loaded with the core purpose. Every clause adds meaningful detail without redundancy. It is concise and well-structured for quick scanning by an agent.

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

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

No output schema exists, but the description covers the essential parameters and behavioral constraints. It doesn't specify the response format or error handling, but for a simple update tool with clear semantics and no nested objects, the description is sufficiently complete for reliable invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the type restriction for destinationUrl and the universal applicability of name/isActive. This goes beyond the schema's field-level descriptions and helps the agent understand parameter interdependencies.

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 explicitly states 'Update an existing QR code's properties' and enumerates specific use cases (changing destination, renaming, enabling/disabling). It clearly distinguishes from sibling tools by focusing on modification rather than creation, deletion, retrieval, or 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?

It provides explicit 'Use this when...' guidance and defines constraints (destination URL only for dynamic types, name/active for any type). This tells the agent exactly when to select this tool and what limitations apply, which is excellent contextual instruction.

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