Shorten a long URL using KooLink and return a compact kool.ink short link. Use this whenever the user wants a shortened URL, a tidy link to share, or a redirect for a long destination.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The destination URL to shorten (http or https). | |
| label | No | Optional label for the API key owner's records. | |
| handle | No | Optional branded short code, e.g. "@chillguyhk". Letters/digits/underscores after the @, 2-30 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states the core behavior (shorten and return a link) and mentions the service (KooLink). However, it does not disclose side effects like whether the link is stored, authentication requirements, or error behavior if the supplied handle is already taken. This is adequate but has clear 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?
Two tight sentences with zero fluff. The core action and result are front-loaded in the first sentence, and the second sentence gives practical usage signals. 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 3-parameter tool, the description covers what it does, when to use it, and what it returns. The lack of an output schema is mitigated by explicitly stating the result is a compact kool.ink short link. It could note error cases or handle conflicts, but those are secondary for typical invocation and are reasonably inferred from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's phrase 'long URL' adds slight context beyond the schema's 'destination URL,' and 'tidy link to share' hints at the use case, but no significant parameter-level meaning is added 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 clear verb and resource: 'Shorten a long URL using KooLink' and explicitly names the outcome 'return a compact kool.ink short link.' It is instantly distinguishable from sibling tools link_stats and list_links, which imply different operations (statistics and listing).
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 explicit usage context: 'Use this whenever the user wants a shortened URL, a tidy link to share, or a redirect for a long destination.' It does not name alternatives or exclusions, but the sibling tools are so clearly different in purpose that little ambiguity remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool serves a clearly distinct purpose: creating a short link, listing links, and fetching stats for a specific link. There is no overlap or ambiguity between them.
Tool names follow a consistent verb_noun pattern: shorten_url, list_links, link_stats. All are lower_snake_case and uniformly readable.
Three tools is a reasonable, focused scope for a URL shortener server. It is slightly minimal but each tool covers a core need without unnecessary bloat.
The core URL shortening workflow is covered: create, list, and analyze performance. Missing update/delete capabilities are minor gaps since users can still manage links through the KooLink UI, but the tool surface has no obvious dead ends for its primary purpose.