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

Annotations already disclose readOnlyHint=true, so the description adds value with API key behavior (anonymous allowance without a key) and what the report contains. It goes beyond the annotation without contradicting it.

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, front-loaded with the main action, and contains no redundant phrasing. Every word contributes to understanding.

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 without an output schema, the description fully covers what it reports (live vs allowed) and when to use it (before bulk creates), including the anonymous allowance nuance. No gaps remain.

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, which sets a baseline of 4. The description doesn't need to elaborate on parameter semantics, and the reference to API key context is 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 uses the specific verb 'Report' and clearly identifies the resource: link allowance. It explains exactly what is measured (live links vs. plan allowance) and distinguishes it from sibling tools that create, list, update, or delete links.

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

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

The description explicitly advises using the tool before a bulk create to check for room, which is a clear usage context. However, it doesn't mention when-not-to-use or point to alternatives like the top-tier example does.

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 destructiveHint=true and readOnlyHint=false, but the description adds valuable context about the immediate effect ('the short URL stops working immediately and anyone who already has it will get a 404') and the API key requirement. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the core purpose. It includes the destructive effect, an important caveat, an alternative tool, and an auth requirement—all without unnecessary wording.

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

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

For a single-parameter destructive tool with annotations and no output schema, the description is comprehensive. It explains the immediate consequence (404), suggests a safer alternative, and mentions the API key requirement, covering all critical context a user would need.

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 covers the sole parameter slug at 100% with a clear description ('The link's short code (the part after the domain)'). The tool description does not add additional parameter semantics beyond what the schema already provides, so the baseline of 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 opens with 'Permanently delete a short link,' which is a specific verb+resource statement. It further distinguishes the tool from its sibling update_link by mentioning 'prefer update_link with paused:true,' clearly identifying the difference.

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 provides a when-not-to-use alternative: 'prefer update_link with paused:true if it might be needed again.' It also states the prerequisite 'Requires an API key,' giving clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, but the description adds valuable behavioral context: it states there is no geographic/device/referrer breakdown and that no API key is needed. This goes beyond the annotation by explaining data limits and authentication requirements.

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 with no redundant phrasing. The first sentence clearly states the function, and the second adds important limitations and the no-auth detail, making every sentence purposeful.

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

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

For a one-parameter, read-only tool with no output schema, the description is complete: it explains what it returns, what data is not available, and that no API key is needed. It leaves no major gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 100% (the 'slug' parameter is fully described as the short code). The tool description does not add additional parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Return') and resource ('total number of times a short link has been followed'), clearly defining the tool's purpose. It also distinguishes itself from sibling tools by focusing solely on click count, unlike link management tools such as shorten_link or delete_link.

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

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

The description explicitly states that this is the only click data available and clarifies that no per-visitor breakdown exists, giving clear context for when to use the tool. While it doesn't name alternative tools, it guides usage by setting expectations about what data is not available.

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 include readOnlyHint=true, so the description correctly aligns by describing a read-only listing operation. It adds the API key requirement and clarifies the scope (authenticated account). However, it does not mention pagination, result limits, or other behavioral details, but this is a reasonable amount given the simple 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 only two sentences, front-loaded with the action and resource. The second sentence about requiring an API key is useful authentication context. No filler or redundant wording.

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 tool with simple functionality, the description adequately covers what the tool does, the data returned (destinations and redirect counts), and the API key requirement. It lacks explicit return format or pagination details, but those are not critical for this simple list operation.

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 baseline is 4. The description does not need to add parameter-level detail because the schema is empty and there are no inputs to explain.

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

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

The description uses a specific verb ('List') with a resource ('short links on the authenticated account') and states what is included (destinations and total redirect counts). This clearly distinguishes it from sibling mutation tools like shorten_link, update_link, and delete_link, as well as the more specific get_link_stats.

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

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

The description gives clear context: this lists the short links on the authenticated account. It implies this is the account-level listing tool and differentiates from creating/updating/deleting links, but does not explicitly state when to use it over get_link_stats or mention exclusions.

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 provide no safety hints (all false), so the description carries the full burden. It discloses important behaviors: anonymous links expire and aren't saved, and only total redirect counts are recorded without IPs, geolocation, device data, or referrers. This adds meaningful privacy context beyond the annotations.

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

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

Three sentences, each earning its place: the first states the action, the second explains anonymous behavior, and the third gives usage guidance. No redundancy or filler.

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

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

For a simple single-link creation tool with no output schema and only one required parameter, the description covers purpose, usage, and privacy behavior. It is complete enough for an agent to invoke correctly without further clarification.

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 each parameter (url, slug, expiresInDays) already documented. The description adds no param-specific details beyond the schema, so 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 opens with 'Create a short link for a URL,' a specific verb and resource. It clearly distinguishes from the sibling tool 'shorten_links_bulk' by focusing on a single URL, and the usage line further clarifies its scope.

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

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

Explicitly states when to use: 'Use when the user wants a short or shareable URL, or a link for a QR code.' It doesn't explicitly name alternatives or exclusions, but the singular 'a URL' implies the bulk sibling is for multiple URLs, so usage context is clear.

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

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

The annotations already indicate a write operation (readOnly=false), and the description adds valuable context by mentioning "Requires an API key" and the batch limit of 100. This goes beyond the annotations without contradicting them, though it does not discuss partial failures or idempotency.

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 consists of two concise sentences, each carrying essential information: action/scope and usage guidance. There is no repetition or superfluous 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 bulk-creation tool with one well-documented parameter, the description covers purpose, usage, and authentication requirements. It lacks details about response format or partial failure behavior, but given the tool's straightforward nature and the annotations provided, this is a minor omission.

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 fully documents the only parameter 'links' with descriptions like 'Up to 100 links to create' and nested fields. The tool description does not add significant new parameter-level meaning beyond what the schema already provides, so the baseline of 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 clearly states the tool's action and scope: "Create up to 100 short links in a single request." It distinguishes this from sibling shorten_link by specifying batch creation, making it immediately clear what the tool does and when it differs.

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 second sentence provides explicit guidance: "Use this instead of calling shorten_link repeatedly when shortening several URLs." This directly tells the agent when to choose this tool over the alternative, which is strong usage 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?

Adds useful behavioral context beyond annotations: paused links stop redirecting but are not deleted, an API key is required, and changing destinations requires a paid plan. This is consistent with the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and enriches the agent's understanding of side effects and constraints.

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 concise sentences that front-load the main action. The first sentence states what the tool does, the second clarifies a behavioral nuance, and the third lists requirements. No filler or repetition.

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

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

For a relatively simple tool with three parameters and no output schema, the description covers the primary use cases, constraints, and authentication requirements. Minor gaps exist, such as unspecified behavior when both 'url' and 'paused' are supplied simultaneously, but these are not critical for basic 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?

The schema already documents all three parameters at 100% coverage. The description adds semantic context for two key parameters: the 'url' parameter requires a paid plan, and the 'paused' parameter affects redirect behavior without deletion. This goes beyond the schema's basic property 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?

Clearly states the tool's function with specific verbs 'change' and 'pause/resume' on the resource 'short link'. This distinguishes it from sibling tools: it is not for creating links (shorten_link), deleting links (delete_link), or retrieving stats (get_link_stats).

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 clear context for when to use the tool: updating an existing link's destination or pausing/resuming it. It also states prerequisites (API key) and a condition (paid plan for destination changes). However, it does not explicitly mention alternative tools or when not to use it, so it stops short of full exclusionary guidance.

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