Gajo URL Shortener

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

Annotations cover the safety profile (non-readonly, non-destructive, non-idempotent, closed world), and the description adds real context on top: plan gating and per-device destination behavior including what a desktop visitor sees. It stops short of stating what happens on a customCode collision or whether the link is immediately live, which are the remaining behavioral unknowns for a creation 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?

Three sentences, front-loaded with the Pro gating and the core action, then the routing model, then the sibling routing. Slight overlap with the schema's own device descriptions, but nothing is wasted or buried.

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?

An output schema exists so return values need no explanation, the schema is fully documented, and annotations carry the safety profile. The description is complete enough to call correctly; only edge-case behavior (code collisions, whether the appName lookup can fail) is unaddressed.

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

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

Schema coverage is 100% and the field descriptions already define iosUrl, androidUrl, and the three otherwise modes in detail. The description reinforces the device→destination model but adds no syntax, format, or constraint detail beyond what the schema states, so this sits at the baseline for a fully documented 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 and resource — "create one short link for a mobile app" — and immediately spells out the routing behavior (iOS → App Store, Android → Google Play, desktop → QR page). It explicitly separates itself from shorten_url, so an agent can pick between them without opening either schema.

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

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

It states the selecting condition directly: "Use it for a link that should send people to the right app store; for an ordinary link use shorten_url." It also names a prerequisite ("Pro only"), which is exactly the kind of gating an agent needs before calling.

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 non-readOnly, destructive, idempotent, and closed-world. The description adds genuinely new context: the destination and click history survive, and generated codes are never reassigned, which tells the agent this is a reversible soft-disable despite destructiveHint. It stops short of describing auth requirements or rate limits, so a 4 rather than 5.

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 the core action front-loaded and the alternatives packed into the second; nothing is wasted and no filler precedes the useful information.

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, idempotent, reversible operation with output schema present, the description covers effect, data preservation, code-reuse policy, and sibling routing. Nothing an agent needs to invoke it correctly 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 100% and the single 'code' parameter is already fully documented in the schema (format, examples, full-URL acceptance). The description adds no additional parameter guidance, so the baseline 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?

States a specific verb and resource ('Turn off one of your short links') plus the concrete effect ('stops redirecting'), which immediately distinguishes it from delete_url and update_url. The preservation clause ('keeping its destination and clicks') further pins down exactly which operation this is.

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 names both alternatives with the condition that selects each: reactivate_url to turn it back on, delete_url to erase it for good. Combined with the stated effect (stops redirecting but keeps data), an agent has a complete when-to-use / when-to-use-something-else decision rule.

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 only declare destructive/idempotent/not-read-only; the description goes well beyond them by disclosing exactly what is destroyed (destination and click history erased, redirect stops), that it is irreversible and non-reactivatable, and that the code is never reissued. This is unusually rich disclosure for a destructive mutation.

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 tight sentences, front-loaded with the irreversible consequence, then the use case, then the alternative. Every clause carries information an agent needs; nothing is padding.

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?

Output schema exists so return values need not be described, and the single required param is fully covered by the schema. The description supplies the full behavioral and routing context, leaving no gap for an agent to fill.

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

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

Schema coverage is 100% and the single 'code' parameter is fully documented in the schema (format, examples, full-URL acceptance), so the description adds no syntax or format detail. The note that the code is never given to anyone else touches the parameter's lifecycle but is behavioral rather than semantic, so baseline 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?

States a specific verb+resource (permanently delete a short link) with precise scope, and explicitly distinguishes itself from the sibling deactivate_url. An agent can pick this over the other eight siblings without opening a schema.

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?

Gives an explicit use case ('a destination shouldn't be kept, e.g. a URL with a private token') and names the alternative for the softer action ('to just switch a link off, use deactivate_url'). When-to-use and when-not-to-use are both covered.

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 openWorldHint=false, so the safety profile is covered. The description adds that the lookup is scoped to 'your' short links and names the returned fields, but with an output schema present these details are already structured elsewhere, so added behavioral value is modest. No mention of behavior for an unknown code.

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

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

Two short sentences, zero filler, with the core action front-loaded and the disambiguation appended. Every clause 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 one-parameter read tool with annotations, a full schema, and an output schema, the description is nearly sufficient. The only gap is unstated behavior for an invalid or nonexistent code, which the agent may want to know before calling.

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?

Single 'code' parameter with 100% schema description coverage, so the schema already explains the format (short code or full short URL). The description only says 'by code', adding nothing beyond the schema, which is the expected baseline here.

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?

States a specific verb ('look up') and resource ('one of your short links by code') and enumerates the fields returned (destination, click count, status, expiry). This makes it clearly distinguishable from get_url_stats and list_urls without opening either schema.

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 routes the agent: 'Use get_url_stats for clicks per day and where they came from,' naming the alternative and the exact condition that selects it. Nothing about tool choice between these two is left to inference.

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 openWorldHint=false, but the description adds real behavioral context beyond them: bots are excluded from the counts, retention is 7/90/unbounded days by plan, and richer dimensions (referrers, devices, countries, regions) are gated to Basic/Pro. It does not cover error cases or rate limits, but the disclosure load is well carried.

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 dense sentence, front-loaded with the core purpose and the bots-excluded qualifier, followed by the tier breakdown. The stacked clauses and parentheticals make it slightly unwieldy, but no sentence is 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?

An output schema exists, so return values need no explanation, and the description still previews the metric dimensions and their plan gating. For a single-parameter read tool this covers everything an agent needs 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?

With 100% schema description coverage on a single 'code' parameter, the schema already does the heavy lifting, so baseline 3 applies. The description's 'for one of your links' reinforces that it takes exactly one link but adds no format or syntax detail beyond the schema's example values.

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?

States a specific verb and resource ('Get click analytics for one of your links') and immediately scopes the result set ('bots excluded: total clicks and clicks per day'). The per-link framing distinguishes it from siblings like get_usage (account-level) and get_url (metadata), so an agent can route without opening the schema.

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?

Usage is implied by the analytics framing and the plan-tier table, but there is no explicit when-to-use-versus-alternatives statement and no named sibling (e.g., get_url for metadata, get_usage for quota). The tier gating tells the agent what it will get, not when it should choose this tool over another.

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 openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the allowance resets on the 1st of each month (UTC) and per-minute API request limits exist. It does not discuss caching or failure modes, but the reset cadence is a meaningful addition.

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 tightly written sentences: the return contents are front-loaded, followed by the call triggers and the reset caveat. Every clause carries information and nothing is redundant.

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?

An output schema exists, so return-value shape need not be restated. Combined with the annotations covering the safety profile, the description supplies everything an agent needs: what it reports, when to call it, and the monthly reset 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?

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool is 4. No parameter gaps exist to compensate for.

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 ('Shows') and resource ('your plan and quota') and enumerates exactly what is returned: links created and remaining this month, maximum link lifetime, and API requests per minute. This clearly separates it from the URL-management siblings (shorten_url, list_urls, get_url_stats), none of which report account-level plan/limit state.

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

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

It gives explicit trigger conditions: 'Call it before creating many links or after a monthly-limit error.' That is clear when-to-use guidance tied to a concrete workflow. It stops short of naming alternatives or an explicit when-not case, so it sits just below the top band.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: results are ordered newest first, include click counts, and are paginated ("Returns one page; use page to see more"). It does not mention auth requirements or a maximum page depth, which keeps it from a 5.

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 short sentences, front-loaded with purpose and immediately followed by routing and pagination constraints. Every sentence carries distinct information with no repetition of the name or title.

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?

An output schema exists, so return values need not be described, and the description still covers the key shape (paged list with click counts). Pagination, ordering, and sibling routing are all addressed, leaving nothing an agent needs in order to call this 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 coverage is 100%, so baseline is 3; the description earns a bump by explaining the intent of the page parameter in context ("Returns one page; use page to see more"), which tells the agent why pagination exists, not just its type. The limit parameter is left entirely to the schema, so it is not a full 5.

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?

States a specific verb and resource ("List your short links") plus scope details an agent cannot get from the name: newest-first ordering and click counts included. It explicitly names the sibling tools get_url and get_url_stats as different operations, so the agent can discriminate without opening schemas.

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?

Gives explicit use cases ("browse or to find a link's code") and explicit alternatives with the condition that selects them: "for one known code use get_url, and for clicks over time get_url_stats." Nothing is left to inference about routing.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: which link states are ineligible for reactivation, which is an important failure mode an agent can't infer from the schema. It stops short of describing the return payload or permission 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?

Two tight sentences: the positive effect first, then the exceptions and the fallback. Every clause carries information and nothing is repeated.

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?

An output schema exists, so return values need no explanation, and the eligibility rules plus the code semantics make the definition callable without further reading. Only the absence of explicit sibling routing and permission/auth notes keeps it from being fully 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 coverage is 100% and the single `code` parameter is fully documented, including the full-URL fallback. The description only echoes that the code is preserved, adding no new syntax or format guidance beyond the schema, so baseline 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?

States a specific verb (reactivate), the resource (a link), and the exact effect — the same code and destination are restored. That distinguishes it immediately from create/shorten and from update_url, which would change a live link rather than revive a dead one.

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 enumerates the cases where this tool will not work (expired, disabled as unsafe, unassigned custom codes) and points to the alternative, 'create a new link instead'. It doesn't name the sibling tool (shorten_url/create_app_link) that performs the alternative, so the routing is directional but not pinpoint.

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 this is a non-readonly, non-idempotent mutation. The description adds important behavioral context beyond annotations: quota consumption, plan-driven link lifetime, and the branded link format for customCode. It doesn't cover failure modes or rate limits, but the added quota and plan constraints are meaningful.

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 compact sentences, with the primary action and return value front-loaded, followed by plan-level behavior and Pro-specific parameter nuances. 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?

Given full schema coverage, annotations, and an output schema, the description supplies the missing operational context: quota impact, plan-based lifetime, and Pro-only features. It is largely complete, though it could mention error conditions or whether the short URL is immediately active.

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 schema already fully documents all four parameters. The description reinforces Pro-only usage for customCode and fallbackUrl and mentions the branded URL path, but adds little parameter-level detail beyond what the schema provides. 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 gives a specific verb and resource ('Create a gajo.io short link for a URL') and states the return field ('shortUrl'). It distinguishes itself from read/delete/update siblings but only partially separates from create_app_link, since it also mentions deep links with fallbackUrl.

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

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

The description provides clear context about plan-based behavior: links follow the plan's code length and lifetime, count against monthly quota, and Pro-only features are called out. It doesn't explicitly exclude or name alternatives like create_app_link, so it stops short of full when-to-use 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?

The annotations already declare mutation, idempotency, and destructive behavior, so the description does not need to repeat them. It adds useful context that only passed fields change and that the tool is Pro-only, though it does not itself explain the destructive impact covered by 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 short and front-loaded, with the Pro constraint and mutation scope stated first. Every sentence contributes either scope, partial-update behavior, or sibling routing.

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 rich annotations, complete schema coverage, and an output schema, the description supplies the remaining call-critical context: Pro-only availability, partial-update behavior, and when to use update_url instead.

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%, and the schema already explains code, iosUrl, androidUrl, appName, and the otherwise enum in detail. The description only paraphrases the field categories, adding little beyond the structured parameter documentation.

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 and resource: change an app link's App Store or Google Play URL, app name, or fallback page. It also explicitly distinguishes this from update_url, which handles ordinary link destinations.

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

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

It gives a clear prerequisite ("Pro only") and names the alternative tool for ordinary link destinations. An agent can decide between update_app_link and update_url without opening either schema.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context — the Pro plan gate and the ~1 minute propagation delay — but does not say the previous destination is permanently replaced or whether the change is reversible, which matters for a destructive op.

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

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

Two short sentences, zero filler, with the plan restriction and the core action front-loaded before the propagation note.

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?

An output schema exists, so return values need no explanation, and with only two fully documented params the surface is small. What's missing is the destructive consequence — that the old destination is lost — which an agent might want to confirm before calling.

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% and the schema docs both params well, including the short-code format example. The description adds nothing about parameter formats or constraints beyond what the schema already provides, so the baseline 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?

States a precise verb+resource: point an existing short link at a new destination URL. This is clearly distinct from shortening a new link (shorten_url) or toggling state (deactivate_url/reactivate_url), so an agent can route without opening a schema.

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 'Pro only' qualifier gives a real precondition, and 'existing short link' implies the tool is for links that already exist rather than new ones. However, no alternatives are named and there is no explicit statement of when not to use it versus shorten_url or update_app_link.

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