Snip

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

Annotations already flag destructiveHint and idempotentHint, but the description adds real behavioral detail: click history is destroyed, the short link stops resolving within a minute, the ending becomes reusable, and the user must be signed in. That is meaningful context the annotations cannot express.

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 tightly-packed sentence front-loads the destructive action, then the timing and auth constraints, then the alternative. No filler and no repetition of the 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?

For a destructive, no-output-schema mutation, the description covers everything an agent needs: irreversibility scope, timing of effect, auth requirement, confirmation guidance, and a non-destructive alternative. Nothing material 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 `link` parameter already documents the accepted forms (full URL, ending, or id), so the description adds nothing further. Baseline 3 is appropriate when the schema fully carries parameter 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?

States a specific verb and resource ("Permanently deletes one of the user's Snip links and its click history") and clarifies scope beyond the name by noting that click history goes too. It also implicitly distinguishes itself from update_link, which handles pausing.

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 tells the agent to confirm with the user first and names the alternative action ("to pause a link instead, use update_link with disabled true"). This covers both the when and the when-not with a concrete sibling route.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: the authentication requirement and the shape of what comes back (aggregates, per-day breakdown, ranked lists). It says nothing about the plan-based day cap or pagination/limits, which would have pushed this higher.

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

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

Two sentences: the first front-loads the returned data, the second carries the prerequisite and usage examples. No filler, no repetition of the title, and the reader knows the scope and the trigger by the end of the second sentence.

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 no output schema, the description takes on the job of describing return content, and it does so thoroughly (totals, daily breakdown, top links/countries/referrers/devices). Auth requirements and the account-level scope are also stated, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters (days, links) are fully documented in the schema including defaults and plan limits. The description alludes to 'by day' and 'the busiest links', loosely mapping to the two params but adding no syntax or constraint detail. Baseline 3 applies when the schema does the work.

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 (get) and resource (account stats), then enumerates exactly what data is returned: clicks and QR scans, totals, by day, busiest links, top countries/referrers/devices. The scope phrase 'across every link in the user's Snip account' cleanly separates it from get_link_stats without needing 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?

Gives concrete triggering questions ('how are my links doing', 'which link got the most scans this week') and the prerequisite that the user must be signed in. It does not name get_link_stats or state when the per-link tool is preferable, so routing between the two is left partly 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds real context: auth requirements and plan-gated behavior ('by hour of the day on plans with time-of-day analytics'). It doesn't discuss result sparsity when the plan lacks a breakdown, but the additions exceed the annotation baseline.

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 what data comes back, then prerequisites, then the alternative. No filler; each sentence routes or constrains the caller.

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 no output schema, the description compensates by enumerating the returned metrics. Auth, identifier formats, plan limits, and the sibling alternative are all covered, so 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 coverage is 100%, so baseline is 3, but the description adds meaningful context: which identifier forms are accepted (short link, ending, or id) and that hour-of-day data only appears on certain plans, which explains gaps in the 'days' scoped result.

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 ('clicks and QR scans for one of the user's own Snip links') and enumerates the returned breakdowns (totals, by day, by hour, top countries, referring sites, devices). It explicitly distinguishes itself from get_account_stats, so the agent can choose correctly 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?

Names the prerequisite ('Needs the user signed in to Snip ... or an API key') and the alternative with its triggering condition ('For every link at once, use get_account_stats'). Both when-to-use and when-to-use-something-else are 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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: an authentication requirement ('Needs the user signed in to Snip') and the fact that domain creation is out of scope, requiring a DNS record in the dashboard.

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: what it returns, how to use the output, and the auth/creation constraint. Every clause carries information and the core purpose is front-loaded.

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

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

For a parameterless, read-only tool with no output schema, the description covers the return content (domains plus live status), the auth prerequisite, and the downstream usage step. Nothing an agent needs to call 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?

Zero parameters, so the baseline is 4. The 'domain' mention refers to an argument of shorten_link, not this tool, so it does not misrepresent the schema; there is simply nothing further to document.

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?

Names the specific resource (the user's own domains, with the go.yourbrand.com example) and what is returned about each ('whether each is live'). An agent can immediately distinguish this from list_links or get_link_stats.

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

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

Explicitly routes the agent forward ('Pass a live one as domain to shorten_link') and states when this tool is not the answer ('adding a domain happens in the dashboard'). Both the use case and the boundary are 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds real value beyond that: result ordering (newest first), the auth requirement, and what each row contains (destination and click count).

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 filler; the resource and ordering come first, followed by prerequisite and the search hint. Every clause carries 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?

With only two simple optional params, no output schema and full annotation coverage, the description supplies what an agent needs: auth requirement, ordering, and the shape of returned data. Missing only explicit pagination/limit behavior and sibling routing.

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 note that search matches "an ending, a destination or a title" largely restates the schema text, and the limit parameter is not addressed at all.

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 (list) and resource (the user's Snip links), plus scope (the user's own links, newest first) and payload (destinations and click counts). This clearly distinguishes it from siblings like list_domains or get_link_stats without needing 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?

"Needs the user signed in to Snip" gives an explicit prerequisite, and the search guidance tells the agent when the search parameter is appropriate. There is no explicit routing to alternatives (e.g., get_link_stats for a single link), 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?

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely new behavior: no account/free, static codes never expire and keep working without Snip, and the output is a PNG plus an SVG download link that should be shown to the user.

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?

Content type enumeration and the return-value/instruction sentence are front-loaded and each sentence earns its place. Slightly long, but 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?

With no output schema, the description correctly carries the return-value burden: it names the PNG and SVG download link and instructs the agent to show the PNG to the user. Combined with the usage routing, an agent has everything needed to call and present the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to the `data` parameter by naming the concrete accepted forms (WIFI:T:WPA;S:...;, vCard, mailto:, tel:, sms:) and routing changeable links to shorten_link. The bg/fg/ecc/style options are left entirely to 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 and resource ("Make a static QR code") and enumerates the supported content types (link, text, Wi-Fi, contact card, email, phone, SMS). It also distinguishes itself from the sibling shorten_link by noting that static codes hold content in the pattern.

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 an explicit trigger ("Use this whenever the user asks for a QR code") plus a routing rule to a sibling: use shorten_link instead for a link the user may want to change or track later. Both when-to-use and the alternative are named.

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?

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false) by explaining the anonymous-vs-signed-in split: unsigned calls return a claim link and work immediately, signed-in calls save to the account and allow a custom ending. This auth/precondition detail is exactly the context the annotations cannot carry.

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?

Front-loads the core action in the first sentence and keeps behavioral detail in the following two. Slightly repetitive around the signed-in/not-signed-in distinction, but every sentence contributes and 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?

For a 4-param creation tool with no output schema, it covers purpose, triggers, auth preconditions, and even the shape of the response (a claim link). Only the exact return payload beyond the claim link is left unstated, which is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds usage-level context for the optional parameters — title, domain, and ending all require a signed-in account (and domain requires a plan with own domains). That precondition framing is more useful than the terse per-field schema text.

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 a long web address into a short snip.link link') and adds the QR-code byproduct. Clear enough to distinguish from list_links/delete_link, but it never explicitly differentiates itself from make_qr_code, which it partially overlaps with.

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 concrete triggers: 'when the user wants a short link, a link they can change after printing, or click and scan counts.' That is clear when-to-use context, though it names no alternative tool (e.g., update_link) and states no when-not-to-use condition.

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-read-only, idempotent, non-destructive, open-world behavior. The description adds genuinely new operational context beyond that: printed QR codes follow the new destination within about a minute (a propagation delay the agent cannot infer from annotations) and the sign-in requirement. It says nothing about failure modes or what happens to untouched fields beyond 'pass only the fields to change'.

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?

Four short sentences, front-loaded with the mutation scope, followed by the side effect, the auth prerequisite, and the invocation rule. No sentence is redundant and nothing is 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?

For a single-resource partial-update tool with no output schema, the description covers scope, side effects on printed QR codes, auth requirement, and update semantics. An agent has everything needed to call it correctly and to set user expectations about latency.

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 and the schema already documents every field including the 404 behavior of disabled. The description adds real meaning on top: the partial-update rule ('pass only the fields to change') tells the agent omitted fields are left untouched, which the schema's absence of defaults does not make explicit.

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 (changes a Snip link) and enumerates the mutable dimensions: destination, title, enabled/disabled state. An agent can distinguish this from delete_link (removal) and shorten_link (creation) without opening any 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 clear context for use: it operates on one of the user's existing links, requires the user signed in to Snip, and instructs 'Pass only the fields to change', which defines the partial-update contract. It does not name an alternative tool 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.