openqr

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

No annotations are provided, so the description must bear the full burden. It mentions a limit of 200 codes, which is useful, but does not disclose behavioral traits such as atomicity, error handling, rate limits, or whether partial success occurs. A bulk creation tool requires more disclosure.

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

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

The description is extremely concise with only two short sentences, front-loading the core purpose and a key prerequisite. Every word contributes to understanding the tool's function.

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

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

Given the tool's complexity (bulk creation), lack of output schema, and no annotations, the description is overly minimal. It omits critical context such as return value, error behavior, validation rules, and handling of duplicates, leaving the agent underinformed.

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 description adds little beyond the schema. It does mention 'up to 200' which is a constraint on the 'codes' array not in the schema, providing slight added value. However, it does not elaborate on parameter semantics like the format of 'destination' or 'theme'.

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 function: 'Create up to 200 dynamic QR codes at once.' The verb 'create' and resource 'dynamic QR codes' are specific, and the bulk aspect differentiates it from sibling tool 'create_dynamic_qr' which implies single creation.

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 includes a prerequisite ('Requires an OpenQR API key') but does not provide guidance on when to use this tool versus alternatives like 'create_dynamic_qr' or when not to use it. The context of sibling tools implies single vs bulk, but explicit exclusions are missing.

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

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

With no annotations, the description carries the full burden of disclosure. It explains the mutation (releasing the subdomain), the behavior (codes remain live on the plain link, only the branded form stops resolving), and the consequence (the name becomes claimable). It also notes the API key requirement. This adds meaningful behavioral context beyond a simple 'release' statement.

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, front-loaded with the purpose, followed by the effect and the auth requirement. Every sentence adds value, with no filler or repetition. It is appropriately sized for a simple no-parameter 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?

The description covers the main context: what the tool does, what happens to existing codes, the resolution impact, the claimability of the name, and the API key requirement. With no output schema, it could explain the response format, but the behavioral outcomes are already described. It is near complete for a tool of this simplicity.

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 burden. The schema coverage is trivially 100%, and the baseline for 0 params is 4. The description doesn't need to explain parameters since none exist, but it does add context about the subdomain name in the URL (via {name}) which is helpful.

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: 'Release the branded subdomain.' It further clarifies the effect by stating that codes stay live on the plain short link and only the {name}.oqr.to form stops resolving, which clearly distinguishes it from sibling tools like set_subdomain and get_subdomain.

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 is implied rather than explicitly stated. The description explains the purpose and consequence but does not explicitly mention when to use this tool versus alternatives like set_subdomain or get_subdomain. There is no exclusionary guidance, so it relies on the reader to infer the context.

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

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

With no annotations, the description must disclose behaviors. It highlights that the QR code is editable (destination changeable later), which is key. However, it does not mention side effects, quotas, rate limits, or what happens on failure.

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

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

Two succinct sentences: the first defines the tool's core purpose, the second a critical requirement. No unnecessary words, 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?

The description covers the purpose and a key prerequisite, but it omits what the tool returns (e.g., QR code data or ID). Given no output schema, this is a notable 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?

All parameters have descriptions in the input schema (100% coverage), so the description adds no extra parameter-level meaning. The mention of 'OpenQR API key' is a prerequisite, not a parameter.

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

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

The description clearly states the action ('Create') and the resource ('an editable (dynamic) QR code'), distinguishing it from siblings like bulk_create_dynamic_qr (bulk) and generate_qr (likely static).

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 mentions a prerequisite ('Requires an OpenQR API key') but does not give explicit guidance on when to use this tool versus alternatives (e.g., when to prefer dynamic over static, or when to choose bulk creation).

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

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

No annotations are provided, so the description carries the full burden. It states a prerequisite (API key) but does not disclose return value, side effects, idempotency, or error conditions. For a mutation tool, this is insufficient.

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, no wasted words. The first sentence states purpose, the second adds a key requirement. Efficient and 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?

The description is adequate for a simple tool with one parameter and no output schema, but lacks details on return value, error handling, and context (e.g., folder parent). Given the sibling tools, it could be more informative.

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

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

With 0% schema description coverage (the 'name' parameter lacks a schema description), the description must compensate. It only implies the parameter through the verb 'Create a folder', adding no format, constraints, or additional context 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 clearly states the verb 'Create' and resource 'folder', with purpose 'to organise codes'. It also mentions the API key requirement. The tool's name differentiates it from siblings like create_dynamic_qr and create_theme.

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 explicit guidance on when or when not to use this tool versus alternatives. The API key requirement is mentioned, but there is no discussion of trade-offs or exclusion criteria.

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 must disclose behavior fully. It states the tool requires an API key and saves a theme, but lacks details on idempotency, error handling (e.g., duplicate names), response format, or side effects. The behavioral disclosure is minimal.

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 two sentences long, front-loading the primary action. No redundant information, though it could be more structured (e.g., separate lines for purpose and parameters). Still, it is concise and every word adds value.

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

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

Given the tool has a nested object (style) with many possible properties, no output schema, and no annotations, the description is adequate but not complete. It lists some style properties but not all, and does not explain the response (e.g., whether an ID is returned). It covers the basics but leaves gaps for an AI 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 coverage is 50% (only style has a description). The description adds examples for style (fgColor, dotType, etc.), providing context beyond the schema's generic 'QR style JSON'. However, the 'name' parameter receives no explanation, so the description only partially compensates for the missing schema descriptions.

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

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

The description clearly states the tool saves a reusable style theme, with a specific verb and resource. It distinguishes from sibling tools like delete_theme and list_themes by focusing on creation. The follow-up explains what 'style' contains, reinforcing the purpose.

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 is given on when to use this tool versus alternatives like create_dynamic_qr or when not to use it. The only prerequisite mentioned is an API key, but there is no comparison with sibling tools or exclusion criteria.

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 provided, so description carries full burden. Discloses destructive nature ('Permanently delete', 'short link stops working') and authentication requirement. No contradictions.

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, each providing essential information: action+effect, and requirement. No unnecessary words.

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, description covers what the tool does, what effect it has, and what is needed to use it. No missing critical info.

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 description for 'id' matches schema. Does not add additional meaning beyond the schema's 'The dynamic code id.' 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?

Clearly states verb 'delete' and resource 'dynamic QR code', and explains consequence 'short link stops working'. Distinguishes from sibling delete tools like delete_folder and delete_theme.

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

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

States prerequisite 'Requires an OpenQR API key'. Context makes clear this is for deletion of dynamic QR codes; alternatives are for other purposes, but explicit when-not guidance is missing.

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

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

The description discloses that codes become unfiled rather than deleted, which is a useful behavioral detail. However, no annotations exist, and the description does not mention whether the deletion is reversible or what other side effects occur, leaving gaps in transparency.

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 one sentence, very concise and front-loaded. It wastes no words, but it could include more detail without being overly long, so it is not perfect.

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 low parameter count (1), no output schema, and 13 sibling tools, the description is incomplete. It does not explain the return value, how to find the folder ID, or how this tool relates to other delete tools. More context is necessary for effective use.

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

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

The schema has one required parameter 'id' with no description. The tool description does not explain what 'id' refers to or how to obtain it, failing to add meaning beyond the schema. With 0% schema description coverage, the description should compensate but does not.

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

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

The description clearly states the tool's action ('Delete a folder') and adds a specific side-effect ('its codes are un-filed, not deleted'). This distinguishes it from sibling deletion tools like delete_dynamic_qr and delete_theme, which do not have that behavior.

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 mentions the prerequisite 'Requires an OpenQR API key' but provides no guidance on when to use this tool versus alternatives or when not to use it. With 13 sibling tools, more comparative usage context is needed.

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

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

With no annotations provided, the description carries the full burden. It discloses that deleting a theme does not affect already-styled codes, a behavioral trait beyond the basic delete operation. It does not cover reversibility or error handling, but adds meaningful 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?

Two sentences, front-loaded with the action and resource. No redundant words; every sentence adds value.

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

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

Given the tool's simplicity (one param, no output schema, no annotations), the description is fairly complete. It covers the core behavior and a key side effect. It lacks details like error handling, but is adequate for the tool's complexity.

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

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

Schema coverage is 0%, and the description does not explain the 'id' parameter at all. It only mentions 'a saved theme' without linking to the required parameter. No additional meaning is provided 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 clearly states the action 'Delete' and the resource 'a saved theme', and adds a key behavioral note about existing codes keeping their look, which distinguishes it from sibling tools like create_theme or update_dynamic_qr.

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 mentions a prerequisite ('Requires an OpenQR API key'), providing useful context. It does not explicitly state when to use vs alternatives, but the sibling list makes the purpose clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses the API key requirement and output formats (PNG/SVG). However, it omits details like potential error conditions, rate limits, or whether the tool has side effects.

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 concise with two focused sentences. It front-loads the primary action and resources, followed by essential details (output format, authentication). No unnecessary words.

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

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

Given the tool's simplicity and that no output schema exists, the description covers inputs, output format, and authentication. It lacks details on error handling, return value structure, or usage constraints, which could be helpful but not critical for a straightforward QR generation tool.

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

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

The input schema covers all parameters with descriptions, achieving 100% coverage. The description adds minimal value beyond the schema, merely restating that the tool works with text/URLs and mentioning output formats.

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 generates a static QR code from text/URL and returns a PNG image or SVG markup. It distinguishes from sibling tools like create_dynamic_qr by specifying 'static QR code', indicating the appropriate use case.

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 this tool is for static QR codes but does not explicitly compare with alternatives like create_dynamic_qr. It provides no guidance on when not to use it or prerequisites beyond an API key.

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 must carry the behavioral transparency burden. It adds an authentication requirement (API key) and lists the specific fields returned, which is valuable. However, it does not explicitly state whether the operation is read-only, how errors are handled, or any rate limits or pagination behavior, leaving gaps for a tool without annotations.

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

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

The description is concise and well-structured: two sentences that clearly state the purpose, list return fields, and note the API key requirement. There is no redundant information, and every sentence earns its place.

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

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

For a simple get-by-id tool, the description is largely complete. It states the operation, the return fields, and the auth requirement. There is no output schema, so the description's listing of returned details is helpful. It does not mention error cases or id format, but these are not essential for basic usage.

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

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

Schema coverage is 100% with the 'id' parameter described as 'The code id,' which is basic. The description does not add significant extra meaning about the parameter beyond identifying it as the key for retrieval. Given the high schema coverage, 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 identifies the tool as retrieving full details of a single QR code by id, enumerating the returned fields. It distinguishes from sibling tools like list_dynamic_qr (which lists all codes) and get_scans (which retrieves scan statistics) by focusing on a single resource and its attributes.

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

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

The description implies when to use the tool (when you need details of one QR code by id) but does not explicitly contrast it with alternatives. It lacks any mention of when not to use it or references to sibling tools. The phrase 'one of your QR codes' provides some context, but no explicit guidance is given.

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?

Without annotations, the description must disclose behavioral traits. It states it's a read operation and requires an API key, but omits details like rate limits, return format, or whether statistics are aggregated.

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

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

A single sentence that is concise and front-loaded with the core action. However, it could be slightly expanded to include return type without losing conciseness.

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 tool with no output schema, the description should hint at the nature of returned statistics (e.g., total scans, timeseries) to ensure the agent understands the tool's output. It lacks this 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 coverage is 100% (one parameter with description). The description adds no additional meaning beyond 'The dynamic code id.' Baseline 3 applies as schema already covers the parameter.

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

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

The description clearly states the action ('Get scan statistics') and the resource ('dynamic QR code'). It distinguishes this tool from siblings like list_dynamic_qr, which lists codes, and others that create or delete.

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 mentions a prerequisite (API key) but provides no guidance on when to use this tool over alternatives, such as when to retrieve statistics versus listing codes.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key behavior: reporting suspension status and explaining that a suspended subdomain redirects to the plain short link. This gives the agent a clear understanding of what the tool does and why it matters.

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

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

Three sentences, each with a distinct purpose: identifying what is shown, explaining the suspension behavior, and stating the API key requirement. There is no redundancy or unnecessary 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?

For a simple parameterless getter with no output schema, the description is fully adequate. It explains what the tool returns (subdomain and suspension status) and provides enough context about suspension to make the tool's output understandable without additional documentation.

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 the schema is trivially complete. The description adds value by explaining the subdomain format and the suspension logic, which is more than sufficient for a parameterless getter.

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 shows the branded subdomain on the account and also reports whether it is suspended. It includes a concrete format ({name}.oqr.to) and effectively distinguishes itself from sibling mutation tools like set_subdomain and clear_subdomain.

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 clear context by explaining that the suspension status is relevant when a Pro plan lapses and mentions the API key requirement. While it does not explicitly name alternatives, the read-only nature is evident from 'Show' and 'Reports', and the sibling names make the usage context clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses that an API key is required and lists return fields, but does not mention non-destructive behavior, rate limits, or pagination behavior beyond the limit parameter.

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 that conveys the tool's purpose and a key prerequisite without unnecessary words.

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

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

Given the tool has one optional parameter, no output schema, and no annotations, the description covers the core functionality and a prerequisite. It is mostly complete, though it could mention default behavior for the limit parameter.

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 existing parameter description in the schema already explains the limit parameter. The description adds no additional 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 clearly states the tool lists dynamic QR codes and specifies the returned fields (id, short URL, destination, label, status). It distinguishes from sibling tools like create, delete, and 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?

The description mentions a prerequisite (OpenQR API key) but does not provide guidance on when to use this tool versus alternatives, such as when to use list_folders or get_scans instead.

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 reveals the authentication requirement but omits other behavioral traits like data freshness, pagination, or performance implications.

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 extremely concise (two sentences) and front-loaded with the core action. Every word serves a purpose.

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 no output schema, the description mentions returned fields (id and name), which is good. However, it lacks details on sorting, filtering, or limits, which are relevant for a list tool.

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

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

There are no parameters, and schema coverage is 100%. The description adds value by clarifying the tool returns the user's own folders, but no parameter info 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?

The description clearly states the action ('list') and resource ('folders'), and specifies the returned fields (id and name). However, it does not explicitly differentiate from sibling list tools like list_dynamic_qr.

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?

Only the prerequisite (OpenQR API key) is mentioned. No guidance on when to use this tool versus alternatives like list_dynamic_qr or list_themes.

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?

Describes it as a list operation, implying read-only. No further details on limits or pagination, but adequate for a simple list with no annotations.

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

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

Two sentences: one for purpose and output, one for usage hint and requirement. Every word contributes.

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?

Covers purpose, output, and prerequisite. Lacks details on error handling or ordering, but acceptable for a straightforward listing tool.

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

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

No parameters, so schema coverage is 100%. Description adds value by specifying output fields (id, name) beyond the empty 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?

Clearly states it lists saved themes with id and name, explicitly differentiating from sibling tools like create_theme or delete_theme.

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 when to use (to get themes for other tools) and the API key requirement. Lacks explicit exclusions but context is sufficient.

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 discloses important behavioral traits: account tier (Pro), auth requirement (API key), and a safety guarantee ('changing this never breaks anything already printed'). This goes beyond a basic 'sets subdomain' statement.

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

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

Three sentences, each adding essential information: purpose, Pro requirement, safety guarantee, and auth requirement. No fluff and 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?

For a simple single-parameter tool with no output schema, the description covers purpose, prerequisites, and a key behavioral guarantee. It's nearly complete, though it could mention what happens if the subdomain is already taken, but that's not essential.

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 already fully describes the only parameter ('subdomain' with format and example), so the description adds no additional parameter semantics. Baseline of 3 is appropriate given 100% schema coverage.

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

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

The description uses a specific verb ('Claim or change') and resource ('branded subdomain') and explains the purpose ('so codes also resolve at {name}.oqr.to'). It distinguishes this from sibling tools like clear_subdomain and get_subdomain.

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

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

It gives clear context by noting 'Pro only' and 'Requires an OpenQR API key', indicating when it's applicable. However, it doesn't explicitly state when not to use it or mention alternatives, though the sibling tool names imply those.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses the partial-update model and API key requirement, but doesn't describe immediate effects, validation behavior, or error handling. It's adequate but not rich, so 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?

Two sentences, front-loaded with the action, and every word earns its place. No filler or redundancy.

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

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

Given 11 parameters and no output schema, the description gives a solid overview of the update operation and its key constraints (partial updates, API key). It doesn't enumerate special conditions (e.g., Pro requirements for pin/password) but those are covered in the schema, so the description remains 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?

The schema provides 100% parameter coverage, so the baseline is 3. The description adds value by explaining the partial-update semantic ('Pass only the fields you want to change') and mapping 'custom short link' to slug, which helps disambiguate parameter intent 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 uses a specific verb ('Edit') and explicitly names the resource ('dynamic QR code') and the changable attributes (destination, label, slug, tags, folder). This clearly distinguishes it from create/delete/get/list siblings.

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 a clear usage instruction ('Pass only the fields you want to change') and notes the API key prerequisite. It doesn't explicitly mention when to avoid using this tool (e.g., for bulk updates), but the partial-update guidance implies the natural use case.

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