Appy smart links

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description confirms the tool returns the new link with its public url, which is useful. It adds no context on permissions, plan limits (parameterForwarding is noted as Business/Enterprise only in the schema, not the description), or failure behavior, so it goes only slightly 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?

Two sentences, front-loaded with the action and the required parameter, then a compact coverage list. The clause enumerating five optional fields is dense but each item maps to a real parameter, so little is wasted.

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 an 8-parameter tool with nested objects and no output schema, it covers the required field, the major optional groups and the return value. Remaining gaps (title, parameterForwarding's plan restriction, error cases) are minor given full schema coverage and clear 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 description coverage is 100%, so the baseline is 3. The description restates the purpose of most parameters (targets, countryRules, deeplinkUrl, socialPreview, slug) but omits title and parameterForwarding, and adds no syntax or constraint detail beyond what the schema already documents.

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 ("Create a smart link") and notes the minimum requirement (fallbackUrl) plus the return value (the new link with its public url). The create verb cleanly separates it from siblings like update_link, get_link and delete_link.

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

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

The description enumerates optional capabilities (targets, countryRules, deeplinkUrl, socialPreview, slug) but gives no explicit when-to-use guidance, no exclusions, and never names an alternative such as update_link for modifying an existing link.

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, so the safety profile is covered. The description adds genuine value beyond that by explaining the observable effect — the link stops redirecting immediately — which tells the agent the consequence is instant, not eventual.

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 with zero filler: the action first, then the consequence and the caution. Nothing to trim and the most important warning 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 one-parameter destructive tool with annotations and no output schema, the description supplies the key missing pieces: immediate effect and the instruction to confirm. It could note whether deletion is permanent or reversible, but nothing essential for correct invocation is absent.

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 sole parameter 'slug' is documented in the schema as the last part of the link URL, so the schema carries the load. The description adds nothing about the parameter, which is the expected baseline for full 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 uses a specific verb and resource ("Delete a link"), making the operation unambiguous against siblings like create_link or update_link. It stops short of an explicit contrast with siblings, but the name plus verb leave no ambiguity.

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?

"Confirm with the user first" gives one real invocation precondition, which is useful for a destructive action. However, it never states when to delete versus update_link (e.g., disable vs. remove) or what happens on an invalid/unknown slug.

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 establish that this is a read-only, non-open-world operation. The description adds useful behavioral context by naming the returned account details and clarifying that a null link limit means unlimited, which is meaningful information 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 compact sentence with no wasted words. It front-loads the account resource and then enumerates the key returned details efficiently.

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 zero parameters and no output schema, the description carries the burden of explaining what the tool returns. It covers plan, features, link limit, null semantics, and link count, which is sufficient for a simple account lookup, though the exact response structure is not specified.

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

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

The tool has zero parameters, so baseline parameter semantics is 4. The description uses its space to describe returned fields rather than parameters, which is appropriate for a parameterless tool.

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 identifies the resource as the account behind the API key and lists the details returned: plan, included features, link limit, and link count. It lacks an explicit verb like 'retrieve' and does not explicitly distinguish itself from sibling get_account_stats, but the resource is still clear.

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?

There is no explicit guidance on when to use this tool versus alternatives such as get_account_stats. The usage is implied by the content, but the description does not state conditions, exclusions, or preferred alternatives.

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 results aggregate across every link in the account and that the response includes a daily series plus breakdowns, paralleling get_link_stats. It does not cover rate limits or whether the date range is clamped, but the added context is real.

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 with no wasted words; the account-wide scope is front-loaded and the output-shape note follows. Nothing needs trimming or reordering.

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 must convey return shape, and it does so by reference to get_link_stats' daily series and breakdowns. That is reasonably complete for a two-param read tool, though a self-contained one-clause summary of the return value would remove the cross-tool lookup.

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%, with start/end formats and defaults fully documented in the schema. The description only restates "over a date range" and adds no semantics (timezone handling, inclusive bounds, max span) beyond what the schema already provides, 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 and resource (account-wide click counts over a date range) and implicitly contrasts with get_link_stats by scoping to "all of the account's links." It does not distinguish itself from get_top_links or get_link_timeseries, which an agent must infer.

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 account-level scope, and the reference to get_link_stats hints at the relationship between the two tools. There is no explicit guidance on when to pick this over get_top_links or get_link_timeseries, and no statement of prerequisites such as account 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully discloses the shape of the returned resource, but says nothing about behavior for a missing/disabled slug, permissions, or whether unpublished links are returned.

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?

One sentence, front-loaded with the verb and key, and the field list is tight. Nothing redundant or padded.

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 enumeration of returned fields is genuinely valuable, and for a one-parameter read tool almost everything needed to call it is present. The remaining gap is failure behavior when the slug does not resolve.

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?

There is a single parameter and the schema documents it at 100% coverage ('the link slug, the last part of the link URL'). The description only echoes 'by slug' and adds no format, casing, or validation detail beyond the schema, 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 ('Read one link by slug') and enumerates the payload (public url, fallbackUrl, deeplinkUrl, targets, country rules, settings), which separates it from the list_* siblings by cardinality. It never names a sibling explicitly, so it falls short of full differentiation.

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 only implied: 'Read one link by slug' suggests fetching details for a known slug. There is no statement of when to prefer this over list_links or the get_link_stats / get_link_timeseries analytics siblings, and no exclusions or prerequisites.

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 genuine value by itemizing the returned metrics (total/unique clicks, per-day, breakdowns by country, OS, device, browser, referrer, outcome), which is important since there is no output schema. It omits behavior on unknown slugs or empty ranges, hence 4 not 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?

One dense sentence, front-loaded with the resource and scope, followed by the enumerated outputs. 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?

With no output schema, the description compensates by listing the return fields, and the schema covers date defaults. Minor gaps remain around empty results and error behavior for an invalid slug, but nothing essential to calling the tool 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 the schema already documents slug, start and end with formats and defaults. The description only restates that the range is a date range and the target is one link — useful tie-in but no additional syntax or semantics beyond the schema. 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?

The description names a specific verb+resource ('Clicks for one link over a date range') and enumerates the metrics returned, so an agent knows exactly what it retrieves. It doesn't explicitly contrast with close siblings like get_link_timeseries or get_account_stats, which is why it stops short of 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?

Usage is implied by 'for one link over a date range' — the agent can infer it is the per-link aggregate stats call. However, there is no explicit when-to-use/when-not guidance and no mention of the sibling alternatives such as get_link_timeseries for finer granularity or get_account_stats for account-level data.

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 the useful fact that the series is daily and excludes breakdowns, but says nothing about date-range defaults, empty results, or rate limits.

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 with zero filler; the core scope is front-loaded and the usage hint follows immediately.

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 3-parameter read-only list tool with full schema coverage and annotations, the description covers what the tool returns conceptually ('clicks per day'). A note on the result shape (date/count pairs) or behavior with no clicks would close the remaining 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 slug, start and end (including the UTC YYYY-MM-DD format and default windows) are fully documented in the schema. The description only gestures at 'date range' and adds no meaning beyond it, 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+granularity: 'Clicks per day for one link over a date range'. The clause 'without the breakdowns' distinguishes it from the sibling get_link_stats, which presumably offers those breakdowns.

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?

'Use it for trends and charts' gives a clear positive condition, and 'without the breakdowns' implies the when-not case. However, it never names get_link_stats explicitly as the alternative, leaving the agent to infer the 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=true and openWorldHint=false, so safety is covered. The description adds the ordering guarantee ("best first") and account-level scoping, but says nothing about result fields, truncation beyond limit, or why the tool is marked non-idempotent despite being a read.

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 with no filler; the resource and sort order lead, and the use case follows. Nothing is wasted.

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?

All three parameters are optional and fully documented, so calling it is unambiguous, but with no output schema the description never indicates what a ranked row contains (link identifier? click count? campaign?). That leaves a real gap for interpreting results.

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%, with each parameter's format, range, and defaults documented inline. The description only restates the shared date-range concept and adds no per-parameter meaning, 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 concrete resource and operation: the account's links ranked by clicks over a date range, returned best-first. The ranking and sort order clearly separate it from a plain enumeration like list_links, though it never names the sibling explicitly.

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?

"Use it to answer which links or campaigns performed best" implies the use case but offers no when-not guidance and no routing against get_link_stats, get_link_timeseries, or list_links, which an agent could easily confuse with this tool.

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 meaningful behavioral detail by disclosing the exact payload shape (statuses including pending/verifying/active/error, the DNS record, the default-domain flag, and limits.used/limits.max). It omits empty-state behavior and auth specifics, keeping it short of 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?

One dense sentence front-loads the resource and then enumerates return fields, with no filler or repetition. It is long for a single sentence, but every clause carries distinct information (statuses, DNS record, default, limits).

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?

There is no output schema, so the description must carry the return-value burden, and it does so thoroughly. The only remaining gaps are operational details such as empty-domain handling and whether results are ever paginated, which are minor for a zero-parameter list call.

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 disambiguate and the baseline of 4 applies. The description correctly avoids inventing parameters and instead spends its words on what the tool returns.

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 precisely identifies the resource (custom domains) and enumerates what is returned: statuses, DNS record, default flag, and plan limits. The verb is only implied by the tool name, and no sibling tools are named, but the scope is unmistakable against the link/account siblings.

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 through the plan note ('Business and Enterprise plans'), which tells an agent who this applies to. However, there is no explicit when-to-use guidance, no statement of prerequisites beyond the plan, and no named alternative for situations where this tool is not appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds the default sort order and the return shape, but says nothing about pagination behavior, result caps, or what an empty page looks like — the main behavioral questions for a paged list.

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 with the core behavior front-loaded and no filler. The trailing search sentence is slightly ambiguous in referent, but overall it is tight and readable.

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?

There is no output schema, and the description partially compensates by naming the returned data ('destinations and targets') and the ordering. For a simple, read-only, zero-required-parameter list tool this is nearly complete; only paging semantics are left implicit in 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 limit, offset, and search are already fully documented in the schema. The description adds no syntax or interaction detail beyond restating that search matches slug/title, which is baseline performance 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?

Names a specific verb (List) and resource (the account's links) and adds observable traits: ordering 'newest first' and returned fields 'destinations and targets'. It stops short of distinguishing itself from list-adjacent siblings like get_top_links or get_link, so it is clear but not fully differentiated.

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

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

The second sentence implies that filtering by slug or title is done via this tool's search parameter, which hints at usage. However, it never states when to prefer get_link, get_top_links, or a dedicated search path, and the phrasing 'Use search' reads ambiguously as if referring to another tool.

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, so the bar is lower. The description adds meaningful behavior beyond them: patch-style partial mutation, slug immutability, and that the updated link is returned. It does not warn that some fields are wholesale-replaced or removable, but the schema covers 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?

Three short sentences with zero filler, and the mutation scope constraint is front-loaded before the immutability caveat and the return behavior.

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 an 8-parameter tool with nested objects, the description plus the richly annotated schema covers invocation adequately, and it discloses the return shape even though no output schema exists. Only permissions and the consequences of replacing list-valued fields could be spelled out further.

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 every parameter carries a detailed description, including replacement and removal semantics for countryRules and socialPreview. The description's only parameter-level contribution is the slug immutability note, 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 ("Change an existing link") and adds a hard scope rule that the slug is immutable, which an agent cannot infer from the name. It does not explicitly distinguish itself from create_link or delete_link, but those siblings' names make the split obvious.

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?

"Only the fields you send change" establishes patch rather than replace semantics, which is genuine usage guidance for invoking it correctly. However, nothing says when to prefer this over create_link or delete_link, nor are there stated prerequisites (ownership, permissions).

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