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

With no annotations conveying safety or idempotency, the description carries the full burden of behavioral disclosure. It merely states 'Create' with no details about potential side effects, such as whether an existing customSlug causes failure or if a random slug is generated. The lack of behavioral nuance is a significant gap for a mutation 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 a single, front-loaded sentence with no wasted words, which is concise. However, given the tool's complexity (11 parameters, no schema descriptions), it is under-specified rather than effectively concise. It does not provide the minimal contextual scaffolding needed for a tool with many optional settings.

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 has 11 parameters, no output schema, and no annotations, so the description must shoulder the explanatory burden. The one-sentence description is entirely inadequate for understanding the tool's full behavior, options, and return values. It offers no guidance on how the many parameters affect the resulting short URL.

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 0%, and the description mentions none of the 11 parameters. The description adds no meaning beyond the schema, leaving the agent without any hints about the purpose or usage of parameters like customSlug, maxVisits, or validUntil. This fails to compensate for the sparse 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 (create) and resource (Shlink short URL), which clearly distinguishes it from sibling tools like edit_short_url, delete_short_url, and get_short_url. It is unambiguous about the tool's primary function.

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 context on when to use this tool versus alternatives. It does not mention prerequisites, such as required domains or valid URL formats, nor does it explain scenarios where editing an existing short URL might be more appropriate. The usage is only implied by the tool's 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 indicate destructive and idempotent behavior. The description adds the config requirement (SHLINK_ALLOW_DESTRUCTIVE=true) and the existential scope ('all orphan visits'), plus the permanence of the erase, which goes beyond the structured annotations. No contradiction with readOnlyHint=false or destructiveHint=true.

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 primary action and followed by critical prerequisites. No fluff, every word 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 tool with one parameter and clear annotations (destructive, idempotent), the description covers the essential trigger conditions and scope. It lacks a definition of 'orphan visits' but that is likely provided by sibling list tools. Overall, it is sufficiently complete for an AI agent to invoke correctly, though it could mention that orphan visits are those not associated with any short URL.

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 there is one required parameter (confirm). The description only restates that confirm=true is required, which is already enforced by the schema's const:true. It does not explain the purpose of confirm (e.g., safety confirmation to proceed) or any behavior tied to it, so it adds minimal value 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 ('erase') and resource ('all orphan visits'), clearly distinguishing from siblings like delete_short_url_visits which targets a single URL's visits, and list_orphan_visits which is read-only. The scope is explicit: all orphan visits, not a subset.

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 states the required configuration (SHLINK_ALLOW_DESTRUCTIVE=true) and confirmation parameter (confirm=true), giving clear context for when this tool can be invoked. However, it does not explicitly mention alternatives or when not to use it, such as suggesting list_orphan_visits first or using delete_short_url_visits for targeted deletions.

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. The description adds valuable context by emphasizing the permanent nature of the deletion and explicitly requiring an environment variable and confirm flag. This goes beyond the annotations and helps the agent understand the irreversible impact and safety prerequisites.

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 short, direct sentences. It front-loads the main action ('Permanently delete a short URL') and immediately provides prerequisites. No unnecessary words or repetition of schema details.

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

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

For a destructive operation with no output schema, the description covers the essential aspects: what it does, prerequisites, and the permanent nature. It could be more complete by mentioning that it deletes the URL itself (not associated visits), but the tool name and sibling context make this inferable. Overall, it is sufficient.

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 describes shortCode and domain, covering 67% of parameters. The description adds meaning to the confirm parameter by stating 'confirm=true,' which is not described in the schema. This clarifies that the parameter must be true, filling a gap in 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 clearly states the action: 'Permanently delete a short URL.' This uses a specific verb and resource, and the word 'permanently' distinguishes it from non-destructive operations. It also differentiates from sibling tools like delete_short_url_visits, which target visits rather than the URL itself.

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 prerequisites for usage: it requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true. This gives context on when the tool can be invoked. However, it doesn't explicitly mention alternatives or exclusion criteria, such as 'for deleting visits, use delete_short_url_visits,' so it falls short of a 5.

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

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

Adds valuable behavioral context beyond the annotations: 'permanently erase' signals irreversibility, and the requirement for an environment variable and confirmation parameter is disclosed. This is consistent with the destructiveHint and idempotentHint 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?

A single, front-loaded sentence conveys the purpose and key prerequisites with zero waste.

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 destructive tool with annotations and schema, the description covers the essential aspects: purpose, prerequisite, and permanence. It could mention failure behavior when conditions are unmet, but this is not required given the 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?

Schema already describes shortCode and domain, and confirm is constrained to true. The description only reiterates confirm=true without adding new parameter semantics. With 67% schema coverage, the description adds little 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 states a specific verb ('erase') and a specific resource ('visit history for one short URL'), clearly distinguishing it from sibling tools like delete_short_url (deletes the short URL itself) and delete_orphan_visits (deletes orphan visits).

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?

Clear context is provided by indicating the destructive nature and the required prerequisites (SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true). However, it does not explicitly name alternatives or when not to use this tool, so it stops short of full 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 destructiveHint=true and idempotentHint=true. The description adds the environment variable requirement (SHLINK_ALLOW_DESTRUCTIVE=true) and the need for confirm=true, which are not covered by annotations. This is valuable contextual information beyond the 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?

The description is extremely concise—two short sentences—with the action stated first and prerequisites following. There is no wasted text 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?

The description covers the core purpose, key prerequisites, and both parameters. With annotations covering destructive and idempotent behavior, and no output schema, it lacks only explicit mention of consequences (e.g., irreversibility), which is already implied by destructiveHint.

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 0%, so the description carries the burden. It explicitly references both parameters: 'one or more tags' for the tags array and 'confirm=true' for the confirm boolean, giving functional meaning to both schema properties.

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 action ('Delete') on a specific resource ('one or more tags'), clearly distinguishing this from sibling tools like rename_tag or list_tags. It unambiguously identifies the tool's function.

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 usage prerequisites (SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true), indicating when the tool can be used. It does not explicitly mention alternatives or when not to use, but for a simple delete operation the 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?

Annotations already communicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context such as whether only provided fields are updated, permission requirements, or side effects beyond the operation itself.

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 lean sentence with no fluff, thus it is concise and scannable. However, it is under-specified for the tool's complexity, but that is more a completeness issue than a conciseness one.

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, no output schema, and minimal annotations, this description is severely inadequate. It provides no information about return values, parameter semantics, default behaviors, or update semantics, making it impossible for an agent to correctly invoke the tool without external knowledge.

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 only 9% (only shortCode has a description). The tool description adds no explanation for any of the 11 parameters, leaving ambiguous fields like crawlable, forwardQuery, and validSince/Until without semantic context.

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 'Edit' and the resource 'existing Shlink short URL', making the action and object clear. It distinguishes itself from sibling tools like create_short_url, delete_short_url, and get_short_url.

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 provided on when to use this tool versus alternatives. The word 'existing' implies it's not for new URLs, but there is no explicit mention of prerequisites, when-not-to-use, or pointing to create_short_url for new entries.

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 and idempotentHint=true, so the agent knows this is a safe read operation. The description adds the domain-scoping behavior, which is useful, but beyond that it does not disclose other behavioral traits like pagination, date filtering, or response format.

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 that conveys the core purpose without unnecessary words. It is concise and scannable, though it might be slightly too sparse for the number of parameters involved.

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 6 parameters, no output schema, and no parameter descriptions, the tool requires more context. The description does not explain pagination, date filtering, bot exclusion, or what the response contains, making it incomplete for an agent to invoke correctly without additional information.

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 0%, and the description does not compensate. It only indirectly clarifies the 'domain' parameter via 'under a specific domain', but gives no meaning for page, startDate, endDate, excludeBots, or itemsPerPage. The description adds minimal value beyond the parameter names.

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 the resource ('visits for short URLs under a specific domain'). It distinguishes itself from sibling tools like get_short_url_visits (per-URL visits) and get_tag_visits (per-tag visits) by specifying domain-level 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?

The description implies the use case (when you need visits filtered by domain) but does not explicitly state when to prefer this over alternatives or when not to use it. Sibling tool names suggest scope differences, but no explicit guidance is 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?

The annotations already declare the tool as read-only and idempotent, so the safety profile is known. The description adds the "when configured" condition, which is a behavioral nuance, but it doesn't disclose what happens if Mercure is not configured or what specific information is returned. 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 a single, front-loaded sentence with no filler. Every word contributes to conveying the tool's 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?

For a simple, parameterless, read-only tool, the description is largely adequate. It could be improved by specifying what happens when Mercure is not configured or listing the exact fields returned, but the current description gives a clear enough idea 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 input schema is empty with zero parameters, so the baseline is 4. The description adds no parameter details because none are needed; the tool requires no arguments.

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 "Get" and identifies the resource as "Shlink's Mercure real-time integration information," which clearly distinguishes it from sibling tools handling short URLs, tags, domains, and visits. The qualifier "when configured" adds context about the tool's availability.

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 the tool is for retrieving Mercure configuration details, and the phrase "when configured" suggests a conditional use case. However, it does not explicitly compare to alternatives or state when not to use it, leaving usage guidance implied rather than explicit.

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 and idempotentHint, covering the safety profile. The description adds the useful behavioral detail that it returns a URL rather than binary image data. However, it does not disclose error behavior, URL format details, or any side effects, but for a read-only operation 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 two sentences, front-loaded with the core purpose and followed by a single clarifying note about the return type. Every word earns its place; there is 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 tool with 9 parameters, no output schema, and only 22% schema description coverage, the description is too sparse. It explains the return type but not what the other parameters do (e.g., size, format, errorCorrection), nor does it describe the URL structure or error conditions. The agent would be guessing on most parameters.

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 only 22%, yet the description adds no parameter details beyond naming 'short code'. Optional parameters like size, color, format, margin, bgColor, roundBlockSize, and errorCorrection are left undocumented in both schema and description. The description does not compensate for the low 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 clearly names the action ('Build'), the resource ('public Shlink QR-code image URL'), and the input ('for a short code'). It also distinguishes the tool by stating it returns a URL rather than binary image data, setting it apart from any potential image-downloading 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?

The description implies when to use the tool: when you need a QR-code image URL. The explicit clarification that it returns a URL instead of downloading binary data provides a clear exclusion (if you want binary data, this tool is not appropriate). No alternative tool is named, but none exists among 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=true and idempotentHint=true, so the read-only safety is covered. However, the description adds no additional behavioral context beyond the bare purpose. It does not disclose any details about the response format, whether it returns all rules or only enabled ones, or any edge cases like an unknown shortCode. The description offers no value beyond the annotations and the tool name.

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 key action 'List', and contains no filler or redundant information. Every word contributes to the purpose. It is optimally 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?

For a simple read-only tool with two parameters (one required), annotations covering safety, and no output schema, the description is mostly adequate. It states what it does. However, it omits any mention of the return value (beyond the implied list) or behavior for invalid inputs, which could be valuable given the absence of an output schema. It is not severely lacking but leaves some gaps.

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%: both 'domain' and 'shortCode' have clear descriptions in the input schema. The description adds no further parameter-specific meaning. Since the schema already documents the parameters, the baseline of 3 applies; the description does not need to repeat but also does not enhance understanding.

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: 'List dynamic redirect rules configured for a short URL.' The verb 'List' combined with the resource 'dynamic redirect rules' and the scope 'for a short URL' is specific and unambiguous. It naturally distinguishes from sibling tools like 'set_redirect_rules' (which modifies rules) and other list tools like 'list_short_urls' (which lists URLs, not rules).

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 guidance on when to use this tool versus alternatives. It does not mention that this is the read-only counterpart to 'set_redirect_rules', nor does it describe any prerequisites (e.g., the short URL must exist) or exclusions. The only implied usage is via the verb 'List', which is insufficient.

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 declare readOnlyHint=true and idempotentHint=true, which covers the safety profile. The description adds no additional behavioral context such as error behavior, authentication needs, or response format, but it does not contradict 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?

The description is a single, front-loaded sentence with no redundant words. It conveys the essential purpose efficiently and earns every word.

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 read operation with only two parameters and clear annotations, the description is adequate. It does not explain the return format, but the absence of an output schema reduces the expectation. Minor gap: the word 'details' is vague about what fields are returned, but the tool's simplicity and sibling context make it sufficient.

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 provides 100% description coverage for both parameters: 'shortCode' is explained as 'The Shlink short code' and 'domain' as the domain when non-default. The description adds no extra meaning 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 uses the specific verb 'Get' with a clear resource: 'details for one Shlink short code.' It explicitly scopes to a single short code, distinguishing it from sibling tools like list_short_urls (which lists all) and get_short_url_visits (which retrieves visits).

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 clearly implies usage for retrieving details of a specific short code, contrasting with list_short_urls for multiple codes. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds no behavioral details such as pagination behavior or response format, but it does not contradict annotations. With annotations covering safety, a neutral score 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?

The description is a single, focused sentence with no fluff, front-loading the action and resource.

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 seven parameters for filtering/pagination and the absence of an output schema, a one-line description is insufficient. The agent gets no indication of date filtering, bot exclusion, pagination limits, or expected return structure.

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 29% (only domain and shortCode have descriptions). The description does not mention any of the seven parameters, failing to compensate for the low schema coverage. Parameters like startDate, endDate, excludeBots, and pagination are left unexplained.

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?

Description states 'List visits for one short URL' with a clear verb (List), resource (visits), and scope (one short URL), distinguishing it from domain- or tag-level visit tools. However, it does not explicitly contrast with get_visit_stats, which also targets a single short URL.

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 provided on when to use this tool versus sibling visit tools like get_tag_visits, get_domain_visits, or get_visit_stats. The description only states what it does, not the appropriate context or 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the key behavioral trait of filtering visits by a tag, which is useful context. However, it doesn't disclose pagination behavior, date filtering, or bot exclusion rules, which are relevant 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?

The description is a single, well-structured sentence that front-loads the primary action and scope. Every word contributes meaning, with no fluff or redundancy. It is appropriately concise for the core 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?

With six parameters, 0% schema coverage, and no output schema, the description is too sparse. It fails to mention filtering options (date range, bot exclusion) or pagination, leaving users without enough context to use the tool correctly. The read-only annotation helps but does not compensate for the missing parameter guidance.

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 0%, so the description must compensate. It implicitly covers the 'tag' parameter ('carrying a specific tag') but leaves the other five parameters (page, startDate, endDate, excludeBots, itemsPerPage) completely unexplained. The description adds minimal semantic value for most parameters.

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') and resource ('visits') with a clear scope ('short URLs carrying a specific tag'). This distinguishes it from siblings like get_short_url_visits (single URL) and get_domain_visits (domain-based). The action and target are 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 description implies when to use this tool (when you need visits filtered by a tag) but provides no explicit exclusions or alternatives. It doesn't say 'use this instead of X' or specify prerequisites, so the guidance is only implied by the stated purpose.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety and idempotency. The description adds the 'general' scope, which hints at aggregate/global statistics, but does not disclose behavioral details such as date-range handling, grouping behavior, or response format. 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 a single concise sentence, well-structured and free of fluff. However, the phrase 'from Shlink' is arguably redundant and adds little information. It is concise but not information-dense, though it does not suffer from unnecessary verbosity.

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 4 optional parameters and no output schema, the description is incomplete. It does not clarify what 'general visit statistics' means, how parameters affect the result, or what the return structure looks like. Annotations help with safety, but functionality remains underspecified.

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 4 parameters with 0% description coverage. The description does not mention or explain any parameters like startDate, endDate, groupBy, or excludeBots. Property names are somewhat self-explanatory, but the description adds no semantic value, so it fails to compensate for the lack of 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 retrieves visit statistics, with a specific verb ('Get') and resource ('visit statistics'). The word 'general' distinguishes it from more specific visit tools like get_short_url_visits, though it is somewhat ambiguous about whether it covers all visits or just a subset.

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 provided on when to use this tool versus sibling tools such as get_short_url_visits, get_tag_visits, or get_domain_visits. There is no mention of alternatives 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds a small behavioral nuance with 'configured or used,' clarifying the scope of the list, but lacks details on return format or pagination.

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 concise sentence that states the tool's function without unnecessary words. It is well-structured and front-loaded with the action.

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 no-parameter listing tool with appropriate annotations, the description is mostly complete. It could explicitly mention that it returns all domains without filtering, but the meaning is implied. No output schema exists, so the description doesn't need to explain return values.

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, and the input schema is empty, so the description does not need to elaborate on parameter meaning. A baseline of 4 is appropriate given the simplicity.

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' and identifies the resource 'domains' with a qualifier 'configured or used by Shlink,' making the purpose clear. However, it does not explicitly differentiate from sibling tools like get_domain_visits or set_domain_redirects, which also relate to domains.

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 guidance on when to use this tool versus alternatives. It does not mention any context, exclusions, or related tools, leaving the agent without direction on tool selection.

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 convey read-only and idempotent behavior. The description adds the scoping to valid short URLs, which clarifies the returned set but does not disclose additional behavioral traits like pagination behavior or filtering semantics.

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, with no wasted 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 five parameters and no output schema, the description is too minimal. It does not mention supported pagination, date filtering, or bot exclusion, nor clarify the relationship to orphan visits. Annotations cover safety, but operational context 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 0%, and the description provides no parameter information. The five parameters (page, startDate, endDate, excludeBots, itemsPerPage) are not mentioned, leaving the agent to infer meaning solely from parameter names.

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 the resource (visits that belong to valid short URLs). It distinguishes from sibling list_orphan_visits by explicitly scoping to valid short URLs.

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 this tool (when you want visits for existing short URLs) but does not explicitly mention alternatives or exclusions. Sibling list_orphan_visits is the obvious alternative, but no direct guidance is 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 and idempotentHint, covering the safety profile. The description adds the definition of 'orphan visits' but does not disclose other behavioral aspects such as pagination, date filtering, or default sorting, which are left unspecified.

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, clear sentence with no unnecessary words. It communicates the essential purpose efficiently, which is ideal for a tool of this simplicity.

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 5 parameters and no output schema, the description is under-specified. It only defines what an orphan visit is, but does not explain pagination behavior, filter usage, or what data will be returned. Annotations cover read-only semantics, but that is not enough for an agent to fully understand the tool's behavior.

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 0% and the description provides no explanation of any of the 5 parameters (page, startDate, endDate, excludeBots, itemsPerPage). The agent is left to infer their semantics from parameter names alone, which is insufficient.

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 'List' and the specific resource 'visits that did not resolve to a valid short URL'. This distinguishes it from siblings like list_non_orphan_visits and delete_orphan_visits, making the purpose self-evident.

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 by the name and description: use this tool to see orphan visits. However, there is no explicit guidance on when to use it over alternatives, nor any exclusions or context about typical use cases.

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 disclose readOnlyHint and idempotentHint, so the safety profile is covered. The description adds 'bounded pagination' as a behavioral trait, but does not elaborate on filtering behavior, sorting, or response shape. This is minimal added context beyond 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?

A single sentence, front-loaded with the core action, no redundant words. Every phrase earns its place, making it appropriately 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?

The tool has 7 parameters and no output schema, yet the description is only one sentence. It omits filter semantics, ordering behavior, pagination mechanics, and return type. 'Bounded pagination' is the only behavioral detail, leaving a significant completeness gap for an agent to use the tool effectively.

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 0%, so the description must compensate for lack of parameter documentation. The description mentions 'list and search' and 'pagination' but does not explain any of the 7 parameters (searchTerm, tags, startDate, endDate, orderBy, page, itemsPerPage). Parameter names offer some intuition, but the description adds no concrete semantics.

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 and searches short URLs, using a specific verb and resource. This distinguishes it from siblings like get_short_url (single fetch), create_short_url, or edit_short_url.

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 a browsing/searching use case, but does not explicitly state when to use this tool versus alternatives such as get_short_url for a single lookup or list_tags for tag-only browsing. No exclusions or when-not guidance are 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 and idempotentHint, so the safe read nature is established. The description adds the fact that withStats includes usage and visit statistics, which is useful beyond the schema. However, it does not disclose output format or pagination, so it adds only moderate value.

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 concise sentence that is front-loaded with the verb and resource. Every word contributes value, with no 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 list operation with one optional boolean and no output schema, the description covers the essential behavior and parameter semantics. It could mention return format or examples, but given the tool's simplicity and the existing annotations, it is sufficiently 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 0%, so the description must compensate. It does by explaining that withStats optionally includes usage and visit statistics, giving meaningful context to the boolean parameter. Could be slightly more explicit, but it's sufficient.

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 a specific verb ('List') and resource ('Shlink tags'), and it adds the optional stats feature. However, it does not explicitly distinguish itself from sibling tools like get_tag_visits or delete_tags, 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 description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions or direct users to sibling tools for different needs, leaving usage context entirely 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 indicate the tool is idempotent and non-destructive, and the description adds the important behavioral detail that the rename applies globally ('everywhere'). However, it does not disclose what happens if the new name already exists or whether the operation is atomic, leaving some behavioral gaps.

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 that is concise, front-loaded with the verb 'Rename', and contains no unnecessary words. It effectively communicates the core purpose in minimal space.

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 two-string-parameter tool with clear annotations (idempotent, non-destructive), the description plus schema and annotations cover the essential usage scenario. The only minor gap is lack of detail about edge cases like name conflicts or return values, but these are not critical given the tool's 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?

Schema description coverage is 0%, so the description must compensate for parameter meaning, but it does not explicitly explain that 'oldName' is the current tag and 'newName' is the replacement. Although the parameter names are self-explanatory, the description adds no additional semantic context 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 'Rename a tag everywhere it is used' clearly identifies the action (rename), the resource (tag), and the scope (everywhere it is used). It effectively distinguishes this tool from siblings like delete_tags and list_tags by indicating a global rename operation.

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 phrase 'everywhere it is used' implies the tool is for renaming a tag across all its occurrences, providing some usage context. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions, so the guidance remains implicit rather than explicit.

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 the tool as write-only, idempotent, and non-destructive. The description adds context that these are fallback redirects, which clarifies behavior. However, it does not explain the effect of null values or whether settings are added to or replace existing redirects.

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 efficiently conveys the tool's purpose. There is 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?

The description is adequate for a simple configuration tool with no output schema and optional parameters. However, it lacks explicit semantics for null values and any guidance on when to use this tool relative to siblings, leaving some gaps in completeness.

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 schema_description_coverage at 0%, the description carries the burden. It names the three categories (base URL, invalid short URLs, regular 404 paths) which map directly to the parameter names, but it does not elaborate on the meaning of null or how these parameters interact. The description adds marginal value over the schema's property names.

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 configures fallback redirects, specifying three concrete targets: base URL, invalid short URLs, and regular 404 paths. The verb 'configure' and resource are specific, though it does not explicitly compare to the sibling 'set_redirect_rules'.

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 provided on when to use this tool versus alternatives like 'set_redirect_rules' or other domain-related tools. The description only states what it does, not when it should be chosen.

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 adds the key behavioral detail that rules are evaluated in the provided order, which is critical for understanding how the redirectRules array is interpreted. Annotations already convey idempotency and non-destructiveness, so the order note provides extra value beyond the structured metadata. It does not mention other effects like replacing all existing rules, but 'Replace' already implies that.

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 the core purpose in the first sentence and a critical behavioral note in the second. There is no redundant wording or unnecessary detail, making it highly 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 tool handles a moderately complex mutation with an unstructured array parameter and no output schema. The description explains the core action and order semantics, but it omits information about the return value, potential validation, or the expected structure of redirect-rule objects. This leaves some gaps for an agent that needs to fully understand the operation's 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?

While the schema covers each parameter's basic meaning (domain, shortCode, redirectRules), the description adds semantic value by specifying that rule order matters, which informs how the redirectRules array should be constructed. This goes beyond the schema's generic 'Shlink redirect-rule objects' description, though it still leaves the rule object structure undefined.

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 action ('Replace') on a clear resource ('dynamic redirect rules for a short URL'), which immediately distinguishes it from sibling tools like get_redirect_rules (retrieve) and set_domain_redirects (domain-level). The purpose is unambiguous and focused.

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 through the verb 'Replace' but does not explicitly state when to use this tool versus alternatives such as get_redirect_rules or set_domain_redirects. There is no exclusion or alternative guidance, but the context of 'short URL' and 'redirect rules' makes the primary use case clear enough for an agent to infer.

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 and idempotentHint, so the description carries a lower burden. It adds minimal context by specifying the 'configured' instance, but does not explain what 'healthy' means, the return format, or behavior on failure, offering only modest value 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?

The description is a single short sentence that is direct and front-loaded with the verb 'Check'. It contains no fluff or redundant details, making it highly concise and efficiently 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?

Given the tool's simplicity (no parameters, no output schema), the description covers the core function adequately. However, it omits any indication of what the response looks like or the criteria for 'healthy', which would be useful for an agent invoking the tool and interpreting its result. This is a minor gap rather than a major one.

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 and the schema coverage is 100%, so the description does not need to compensate for parameter documentation. Per the baseline for zero-param tools, a score of 4 is appropriate; the description adds clarity about the tool's purpose but no parameter-specific details are 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 tool's function with a specific verb ('Check') and resource ('configured Shlink instance'), making it unambiguous. It also distinguishes itself from all sibling tools, none of which relate to health checking.

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 implicitly conveys when to use this tool (to verify Shlink health), and no alternative health-check tool exists among siblings. However, it lacks explicit guidance on when not to use it or any prerequisites, so it doesn't fully define usage context.

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