Strait MCP server

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

Annotations only cover readOnly/destructive/openWorld/idempotent flags; the description goes well beyond by disclosing the confirm-gated preview, the plan restriction, the 5-domain cap, and the exact DNS records the caller must add afterward. That is exactly the operational context an agent needs before mutating state.

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 'Write.' marker and the core action, then layers constraints. The single dense paragraph is information-rich but slightly packed; a reader must parse several clauses to find the preview 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?

No output schema exists, and the description compensates by describing the returned DNS records and preview payload. Combined with the plan/limit/confirm disclosures, nothing essential for correct invocation 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; the description adds value by explaining what the preview returns (plan, limit, domains already added) and reinforcing that confirm:true is the switch between no-op and write. Hostname semantics are largely already in 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?

Names a specific verb and resource ('Adds a custom link domain') and even disambiguates what it returns (CNAME + two TXT records). It is clearly distinct from siblings like list_domains and remove_domain.

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 gating conditions: 'Scale and Enterprise only, at most 5 per workspace', and explains that without confirm:true it becomes a preview. It doesn't explicitly route to sibling tools (e.g. list_domains for existing domains), but the when-to-use context is unambiguous.

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: it discloses per-item error isolation ('gets its own result'), the specific failure mode for duplicate slugs (per-item 409, not a whole-batch failure), and that re-runs are therefore safe — context that reinforces idempotentHint with the actual mechanism. It also tells the caller where to look for success, 'results[i].ok', which compensates for the absent output schema.

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: scale and use cases first, per-item semantics second, result-reading instruction last. No filler and nothing 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 bulk mutation with no output schema, it covers scale, atomicity (per-item results, no whole-batch rollback implied), duplicate handling, and retry safety. Remaining gaps are minor: payload-size or rate-limit expectations for a 500-item call and what a per-item validation failure looks like beyond the 409 case.

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?

Only one top-level parameter, and the description adds little beyond the schema: the 500 cap is already maxItems and the minimum is already minItems. The one genuine addition is that item-level validation follows create_link, which is useful but does not explain any item field 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 with scope: 'Create up to 500 links in one call', and immediately frames it against the single-item sibling by noting each item is 'checked like create_link'. An agent can distinguish bulk creation from create_link 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 concrete scenarios (imports, migrations, campaigns) that call for the bulk variant and explains that re-running an import is safe, which is the key decision criterion. It stops short of an explicit 'use create_link for a single link' routing statement, so the alternative is implied rather than stated.

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/non-destructive, so safety is covered; the description adds real value beyond that by stating the output shape (severity ok/warn/error plus a fix) and that no API key is needed. It doesn't mention rate limits or failure behavior for unreachable domains, 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?

Front-loaded with the concrete files checked, then trigger, then scope caveat, then auth note. Dense and nearly waste-free; the parenthetical platform annotations are slightly verbose but useful.

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?

No output schema exists, yet the description tells the agent what findings look like (severity levels and a fix) and sets expectations about what is out of scope (actual device behavior). Nothing needed 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?

Only one parameter and schema coverage is 100%, with the schema already explaining that a full URL is reduced to its host. The description adds no format or edge-case guidance about the domain beyond what the schema states, 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?

Names the exact resources checked (assetlinks.json, apple-app-site-association) and the platforms, so the agent knows this is a domain-level file validator rather than a link tester. It is clearly distinct from siblings like check_link or simulate_tap.

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 trigger condition ('when links open the browser instead of the app') and an explicit scope exclusion ('checks the files the domain serves, not how one particular phone behaves'). It does not name the neighboring tools an agent might confuse it with, such as check_link or simulate_tap, so it stops short of full alternative 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?

Adds real operational context beyond annotations: the input is restricted to public https links, no authentication key is required, and there is a rate limit of a few checks per minute per network. It also describes what the response covers (destination on Android/iPhone/desktop, liveness, remediation advice). The opening 'Read-only' only restates readOnlyHint, but the rate-limit and visibility constraints are the valuable additions.

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 tightly packed sentences with the core capability front-loaded and usage guidance second. The vendor enumeration in sentence one makes it long but each item is load-bearing; minor redundancy in 'Read-only' versus annotations.

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 compensates by stating exactly what the check reports across platforms plus remediation guidance. Combined with the auth and rate-limit notes, an agent has everything needed to decide to call it and interpret 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% for the single url parameter, so the baseline is 3. The description adds a constraint the schema does not express: only public https links are accepted, which tells the agent to reject http, private, or internal URLs before calling.

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 ('checks any deep link') and enumerates the vendor formats it accepts (Firebase page.link, Branch app.link, Strait link, plain URL). This clearly separates it from sibling tools like get_link, check_app_links, simulate_tap, and trace_tap, which check or simulate rather than diagnose an arbitrary external 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?

Gives two concrete triggering situations ('before migrating links' and 'when an old link stopped working'), which is stronger than generic context. It does not explicitly name alternatives such as check_app_links or trace_tap, so the agent must infer the boundary from the sibling list.

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 read-only/idempotent/non-destructive, and the description adds real behavioral detail beyond them: percent change is null when 'before' was 0, the default before-period is same-length just prior, grouped rows are ordered biggest first, days are UTC, and each period is capped at 92 days. No mention of auth or rate limits, 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?

Front-loads 'Read-only.' then defaults, then grouping, then use cases, then the UTC/92-day constraint. Dense single paragraph with no redundant restatement of the schema.

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 compensates by describing the return shape: current vs before values plus change and percent change, with null semantics and ordering for grouped rows. An agent has everything needed to call and interpret it.

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, and the description adds meaning: it explains that 'before' defaults to the equal-length preceding period, that group compares each row and sorts biggest first, and that periods cap at 92 days. It doesn't touch limit or link beyond what the schema says, but the defaulting logic for compareFrom/compareTo is genuinely additive.

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 (compares) and resource (two periods) and enumerates the metrics compared: taps, app opens, installs, conversions, revenue, with change and percent change. The comparison framing clearly distinguishes it from the plain get_analytics sibling.

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

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

Gives concrete usage contexts ('how did this week do against last week', 'why did installs drop'), which is strong when-to-use guidance. It never explicitly names get_analytics as the alternative for single-period reads, so the routing is implied rather than stated.

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 the mutation/safety profile (readOnlyHint=false, openWorldHint=true), so the description's explanation of what the link does — App Links/Universal Links, store-or-website fallback, destination retained through install — adds genuine context. It omits what happens on a duplicate slug or how failures surface, which matters given idempotentHint=false.

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 action and scope, then the return value, then an alternative. The shortUrl host pattern is useful rather than padding; 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?

For a 13-parameter creation tool with no output schema, the description covers the return value (shortUrl to share) and link behavior adequately. Duplicate-slug behavior and error semantics remain undescribed, but this is a minor gap against a rich 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 92%, so the schema already explains slug, longUrl, expiry, fallback URLs and preview fields in detail. The description adds no parameter-level guidance of its own, which is acceptable at this coverage level.

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 one deep link (short link)') plus the scope ('in the workspace of STRAIT_SECRET_KEY'), and distinguishes itself from the bulk sibling. An agent can select it 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?

Explicitly routes bulk work to batch_create_links ('For more than a few links use batch_create_links'), giving a real alternative with a selection condition. No explicit when-not for single creation, but the context is clear.

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, but the description adds real behavioral detail beyond that: end-user traffic falls through to a not-found page, analytics history is preserved, and the action is reversible via update_link. The only omission is any note about permissions or effect on in-flight/redirecting taps.

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-loaded with the effect and the confirm requirement, and every sentence carries information: outcome, data retention, reversibility, confirmation gate. The leading fragment "Write." is slightly odd but functionally signals a mutation; no real 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 usefully notes that a missing confirm returns a preview of the link, covering the return-value gap. For a two-parameter mutation with full annotation coverage this is close to complete, with the pause_link ambiguity being the remaining hole.

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, and the description earns an extra point by explaining the consequence of omitting confirm — you get a preview of the link to show the user, not an error. That is meaning beyond the schema's terse "true to deactivate; omit or false to preview".

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 ("Turns a link off") and describes the observable effect: taps hit a "link not found" page instead of the app, store or website. It does not differentiate from the sibling pause_link, which sounds like it does something very similar, so an agent cannot fully resolve the choice from the description alone.

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?

Explicit about the confirm gate ("needs confirm: true; without it nothing changes") and explicitly names update_link with isActive: true as the way to reverse it. What's missing is guidance on when to use this vs. pause_link, which is the closest alternative in the sibling list.

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, non-destructive, so safety is covered. The description adds behavior the annotations don't: UTC day boundaries, the 92-day-per-call ceiling, and the default 30-day window — all relevant to how calls behave and fail.

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 that front-loads the metric list and scope, then appends grouping and limits. The parenthetical channel examples are slightly long but earn their place by clarifying the enum. No 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?

With no output schema, the description carries the burden of indicating what comes back, and enumerating the metrics largely does that. Aggregation/shape details (e.g., zero-fill for empty days, response envelope) are missing, but an agent has enough 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 75%, and the description fills the main gap by explaining the otherwise-undescribed 'group' enum (day, channel with example values, link, platform) and clarifying the 'or one link' scoping for the link param. It doesn't explain the from/to defaults beyond what the schema already states, so it's good but not exhaustive.

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 resource (analytics metrics: taps, app opens, installs, conversions, revenue) and scope (workspace or one link), plus the grouping dimensions. An agent can distinguish it from list_taps or record_event. It stops short of naming siblings like compare_analytics or get_top_links, so it doesn't fully differentiate.

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 useful operating constraints (92-day cap, 30-day default) and notes parity with the dashboard, which implies when to trust the numbers. However, there is no explicit guidance on when to choose this over compare_analytics, get_top_links, or list_taps, leaving the choice 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 readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds one genuine behavioral detail — only active links are returned — but says nothing about not-found behavior or what happens for paused/deactivated slugs.

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

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

A single front-loaded sentence that enumerates the payload fields without filler; 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 one well-documented parameter, no output schema and full annotation coverage, the description is nearly sufficient — enumerating returned fields (destination, fallbacks, tags, expiry, shortUrl) compensates well for the absent output schema. Missing only failure/empty-result behavior for unknown or inactive slugs.

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 slug parameter already carries a pattern and a concrete URL example, so the schema does the heavy lifting. The description only restates 'by slug' and adds no format or edge-case meaning.

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?

Specific verb and resource ('Get one active link by slug') plus the returned field set make the operation unambiguous and clearly distinct from list_links/search_links, which return many. It stops short of naming a sibling explicitly, so not a 5.

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

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

The phrase 'one active link' implies this is the single-record lookup and hints that non-active links won't be returned, but there is no explicit when-to-use/when-not or pointer to search_links/check_link for other cases.

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

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

Beyond the readOnly/idempotent annotations, it discloses concrete behavior: the return is an image (PNG or SVG markup) plus the exact encoded URL, scans default to utm_source=qr (a real side effect on analytics), and calls are refused with 400 when colour contrast is under 3:1. These are exactly the traits annotations cannot convey.

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?

Effectively front-loaded ('Read-only.' then the resource), and every clause (return format, tracking default, contrast error) carries distinct information. Slightly dense but no wasted sentences.

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 steps up to describe the return (PNG/SVG plus the exact URL) and states the error condition and tracking default. 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?

Schema coverage is 100%, so the schema already documents each parameter; the description adds the relational meaning that options override workspace defaults for this one code and reinforces the contrast rule tied to colours. This is real added context beyond the schema's per-field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('A print-ready QR code for a link') and frames it as read-only. An agent can immediately tell this apart from get_link or get_analytics by the QR/image output it produces.

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 explains that the per-call options override the workspace QR style, which clarifies behavior, but it never says when to choose this over siblings like get_link or when a QR is the appropriate artifact. Usage is implied through the defaults discussion rather than stated.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: UTC day boundaries, the 92-day cap, the default window, and that a workspace without referrals enabled returns an explanatory message rather than an error. It says nothing about auth or rate limits, so not 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?

Sentences are front-loaded with the read-only marker and the report definition, then constraints, then the edge case. No filler and nothing repeated from annotations unnecessarily.

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 two-optional-parameter read tool with no output schema, the description covers what is returned, how it is ordered, default window, maximum span, timezone, and failure-mode behavior. An agent can call it correctly without further inference.

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, and the description earns the bump by supplying the omitted default ('the last 30 days') and the maximum span (92 days), neither of which the schema states for the unbounded `from` parameter. It also fixes the timezone semantics (UTC days), which the schema's date-time format leaves ambiguous.

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 ('read the referral report') and then defines the report's shape: per referral code, the taps that carried it and the referred installs, ordered most-conversions-first. That level of specificity clearly separates it from siblings like get_analytics or get_top_links.

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 operating context: a date range, a default of the last 30 days, and a hard 92-day cap per call. It also notes the graceful path when referrals are not enabled. It does not name an alternative tool or state when to prefer get_analytics over this, 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/non-destructive, and the description still adds real operational context: UTC day boundaries, a hard 92-day maximum window, and a documented 30-day default. It also discloses the shape of the result (per-link share of total), which is not captured anywhere in the structured fields.

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, no redundancy. The read-only/safety statement comes first, then what it ranks and returns, then the time-window constraints — the most decision-relevant information 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?

With no output schema, the description carries the burden of explaining returns and does so adequately ('share of the total'). Parameter defaults and the window cap are covered. Only minor gaps remain, such as how ties or links with zero activity are handled.

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 would be 3, but the description adds information the schema does not: the 92-day maximum span between from and to, and the default window of the last 30 days. The 'by' semantics are reinforced by the ranking phrasing in the description.

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 and resource ('top links over a date range, ranked by taps, app opens, installs or conversions') and states what is returned ('each link's share of the total'). That is enough to separate it from generic analytics siblings, but it never explicitly contrasts itself with get_analytics or compare_analytics, which are the nearest alternatives.

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 provides a concrete when-to-use cue in the quoted example 'which links brought the most installs this month', which maps cleanly onto the 'by' enum. It stops short of saying when not to use it or pointing to a sibling when the agent wants aggregate totals instead of per-link ranking.

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, which only cover read-only/idempotent safety. It discloses that going over never stops a redirect and that new_links_paused means create_link returns 402 until upgrade or month end - non-obvious consequences an agent could not infer. It stops short of stating rate-limit or caching behavior, but the important behavioral semantics are present.

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-loaded with 'Read-only. This calendar month's usage (UTC)...' followed by enumerated return fields and their thresholds. Two sentences, no filler, 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 no output schema and no parameters, the description must carry the return-value burden and does: field meanings, limit/null semantics, level thresholds, and the downstream effect on create_link. An agent has everything needed to call and interpret it.

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 schema imposes no burden and a baseline 4 applies. The description still clarifies return-field semantics (null = no limit, level thresholds at 80% and 100%), which compensates for the absent output 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?

States a specific verb and resource: reads this calendar month's usage against the workspace's plan. It enumerates the exact returned quantities (billed taps used/included, new links created/included, level, new_links_paused), which clearly separates it from analytics siblings like get_analytics and get_workspace.

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 context is implied - check this to know whether the workspace is near or over its plan limits, and why create_link might be answering 402. But no sibling is named and no explicit when-to-use / when-not-to-use rule is given.

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, non-destructive and open-world, so the safety profile is covered; the description adds the valuable disclosure of what the payload contains and that key scope determines write capability, which directly affects planning. It stops short of covering auth failures or error behavior for an invalid key, so it is not fully exhaustive.

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, front-loaded with 'Read-only' and the identity framing, then the enumerated return contents, ending on the actionable 'call it first' guidance. Every clause carries information; the inline domain example earns its space by making 'link domain' concrete.

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 compensates by enumerating exactly what comes back (name, link domain, custom domains, plan, key scope). Combined with annotations covering safety, an agent has everything needed to call it and interpret 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. The description correctly implies the implicit context (the key itself identifies the workspace) rather than inventing param details.

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 exact resource (the workspace and the secret key's identity) and enumerates the returned facets: workspace name, link domain, custom domains, plan, and key scope (full/links/read). It is clearly distinct from siblings like list_domains or get_usage because it frames the key's own identity rather than a collection.

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 trigger — 'Call it first when you need the link domain (for check_app_links) or to know whether the key can write' — naming both the condition and the downstream tool that consumes the result. The agent knows when to reach for this over any other sibling.

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 and destructiveHint=false, so the safety profile is covered. Beyond that, the description explains the status state machine (pending_dns until DNS records are in place, then live; verified once ownership is proven) and the plan gate (Scale and Enterprise) plus the limit, which an agent cannot infer from the schema. It does not cover empty-workspace behavior or auth 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?

Front-loads 'Read-only.' followed by what is returned and then the use case, in three dense sentences with no filler. The parenthetical explanations of statuses are long but each earns its place by preventing misinterpretation of enum-like values.

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 describe returns itself — and it does: domain names, status values, required DNS records, plan eligibility and limit. An agent can decide and act without further information.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly adds no parameter noise and instead spends its space on return-value 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 ('The workspace's custom link domains') and enumerates what each entry contains: status and the exact DNS records to add. It is clearly distinguishable from the mutation siblings add_domain/remove_domain.

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 a concrete trigger phrase, "is my domain set up yet", which tells the agent exactly when to reach for this tool. It stops short of naming alternatives or exclusions (e.g. use add_domain to create one, remove_domain to delete), so it is clear context without full 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?

Beyond the readOnlyHint annotation, the description discloses ordering (newest first), the default 7-day window, the data source (events export), and a concrete permission requirement (an owner's or admin's key). It also enumerates the attributed fields returned, which is real behavioral context rather than restatement.

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 paragraph that front-loads the resource, contents, and default window before the usage hint. The opening 'Read-only' duplicates the annotation, a minor redundancy in an otherwise efficient definition.

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?

No output schema exists, and the description compensates by enumerating the returned fields and their attribution chain. Combined with the auth note and default window, 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 from/to/slug/limit are already documented, including the default window and the 20-item limit. The description restates the default window but adds no syntax or filtering nuances 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 and resource (list recent conversion and revenue events) plus the precise contents returned, ordering, and default window. It is clearly distinguishable from siblings like list_taps, record_event, and get_analytics.

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 ('check that purchases or sign-ups arrive'), which tells the agent when to reach for it. It stops short of naming alternatives (e.g., list_taps for raw tap data or get_analytics for aggregates) or stating when not to use it.

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, but the description adds non-obvious behavior: newest-first ordering, the requirement to iterate with nextCursor until null, and the silent exclusion of abuse-disabled links from the paused set. Return payload shape and page-size behavior are left to the schema.

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 what the tool returns and ordered so pagination mechanics follow the purpose statement. No filler or 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?

With no output schema, the description carries the burden of the return contract and does so by naming nextCursor and the termination condition. Minor gaps remain around what a link record contains and how limit interacts with paging, but nothing needed 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?

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining what 'paused' actually means and noting that abuse-disabled links are excluded from results entirely. The cursor explanation largely restates the schema's 'nextCursor from the previous page'.

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 opens with a specific verb and resource ('List links') and immediately pins down ordering ('newest first') and scope ('one page at a time'). An agent can distinguish it from single-record siblings like get_link or check_link without opening the schema, though it never names search_links as the filtered alternative.

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 paging loop ('Pass nextCursor back as cursor until it is null') and states the default filter, which is real operational guidance. It also points to update_link isActive: true for re-enabling paused links, but never says when to prefer search_links over this plain listing.

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/non-destructive, and the description still adds real value: newest-first ordering, the default one-hour window, and an auth constraint ('Reads the taps export (an owner's or admin's key)') that no annotation conveys. The only redundancy is the leading 'Read-only.', which restates readOnlyHint.

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 sentence is dense but front-loaded: scope and ordering come first, the field enumeration in the middle, use case and access requirement at the end. The parenthetical field list is long but justified because there is no output schema; the only wasted token is the redundant 'Read-only.' opener.

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 carries the return-shape burden well by listing the fields and their meaning (sent_to, match_method, open_kind). Combined with the default window and key-permission note, an agent can call it correctly; only a pointer to sibling tools for narrower or broader queries 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 baseline is 3, but the description adds the implicit default window ('the last hour') that the schema leaves unstated for `from`, plus the newest-first ordering that governs how `limit` and the time bounds are consumed. It says nothing extra about `slug` or boundary inclusivity 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 names the resource precisely ('Recent individual taps, newest first') and enumerates the per-tap fields returned (when, link, platform, channel, sent_to, opened_at, open_kind, installed_at, match_method), so an agent knows exactly what the payload holds. It stops short of explicitly contrasting with near-neighbors like list_events or trace_tap, so it's 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?

'Use it to check that a test tap was recorded and what happened to it' gives a concrete triggering scenario, and 'Default: the last hour' sets the default window expectation. It does not name alternatives (e.g., trace_tap for a single tap's journey, list_events for broader events) or state when not to use it.

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?

Beyond the read-only annotations, the description discloses retention (30 days), ordering (newest first), status semantics (pending/delivered/failed after 6 attempts), permanent-error behavior, and the important constraint that payloads are never returned. This is rich behavioral context that an agent needs in order to interpret results correctly.

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 dense paragraph with zero obvious waste. It front-loads read-only status and then proceeds from core behavior to status semantics to the omitted-parameter fallback and usage scenario.

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 carries the burden of explaining return contents, and it does so: event status, attempts, last HTTP status/error, next retry time, and the fact that payloads are excluded. It also covers the alternate listing mode, making the definition complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents limit, cursor, and webhookId. The description reinforces the optional webhookId behavior, but it does not add syntax or format detail beyond what the schema provides for pagination parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: listing a webhook's delivery history. It also defines ordering, retention, and the fallback behavior when webhookId is omitted, which clearly distinguishes it from the sibling list_webhooks tool.

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 explicitly says to use the tool when a webhook seems to have stopped, and it explains that omitting webhookId lists workspace webhooks so the caller can choose one. It does not explicitly name alternatives or when-not-to-use conditions, but the operational context is clear.

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/non-destructive, but the description goes further with context structured fields cannot carry: receiver URLs are truncated to the host because they often embed a secret, and signing secrets are never returned. That is exactly the kind of privacy/security behavior an agent needs before relaying output to a 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?

Front-loaded with the safety note and the returned-field list, and the parenthetical about secrets is well placed. The opening 'Read-only.' is slightly redundant with readOnlyHint=true, and the second sentence is long and comma-stacked, but no sentence 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?

There is no output schema, so the description must describe the return shape — and it does, field by field, including the important caveat that URLs are host-only. Combined with the downstream-tool pointers and the creation path, an agent has everything needed to call this and act on 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It spends its words instead on the shape of the returned records, which is the relevant substitute 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?

The description enumerates exactly what the workspace resource contains (id, receiver host, subscribed events, enabled flag), which pins down a single-resource list operation despite the noun-phrase phrasing. Naming list_webhook_deliveries and test_webhook as the follow-on consumers separates it from those siblings without the agent needing to open 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?

Explicitly routes the agent: take the returned id to list_webhook_deliveries or test_webhook, and notes that webhooks are created via Dashboard → Settings → Webhooks rather than an API call — useful since no create_webhook sibling exists. It stops short of stating when not to call it (e.g., that deliveries/attempt history lives elsewhere), so it is clear context rather than a full decision tree.

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

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

Annotations declare destructive, idempotent and non-read-only, and the description goes beyond them: it says exactly what breaks (all taps hit the not-found page), what survives (history stays in analytics), and that the write is gated behind confirm so a preview is side-effect free. That is the reversal, blast radius and safety interlock all in one place.

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, mutation flag and effect front-loaded, then the confirm gate, then the undo path. Nothing repeats 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?

With annotations carrying the safety profile and no output schema, the description covers effect, reversibility, analytics impact and the confirm gate. The only thing an agent might still want is how this differs from deactivate_link, which is a sibling it will see in the list.

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 are already documented. The description nonetheless adds meaning the schema does not — that omitting confirm is a no-op returning a preview the caller can show a user, and that resume_link is the inverse operation.

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 (pause a link) and spells out the observable effect: every tap serves a "link not found" page instead of the app, store or website. That effect distinguishes it from neighbors like deactivate_link and resume_link without the agent 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 explicit operational guidance: needs confirm:true, otherwise nothing changes and you get a preview to show the user, and undo with resume_link. The one gap is that it never contrasts pause with deactivate_link, so an agent cannot tell from the description why it would pick one over the other.

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: discloses the confirm-gate dry-run semantics, that the event feeds analytics/revenue and app.event webhooks, that secret_key authentication is required, and that eventId dedupes retries. The only friction is that the stated eventId idempotency sits in mild tension with idempotentHint=false, though that hint is reasonably read as 'not idempotent by default'.

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 action and the most consequential constraint (confirm gate) before the identity fields. Dense but nearly every clause carries information; the 'Write.' lead-in is slightly terse relative to the rest but harmless.

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 9-parameter mutation with a nested data object and no output schema, the description covers the decisions an agent must make: whether to call at all (SDK preferred), the confirm gate, and retry safety. Return shape is only gestured at ('you get a preview'), which is the remaining 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 the baseline is 3, but the description adds genuine meaning: clickId's origin (apps get it from the SDK), eventId's purpose (your order id, safe retries), and confirm's effect. value, currency, platform, and data are left to the schema, which already documents them well.

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?

Opens with the verb 'Write' and states precisely what is recorded: one conversion or revenue event from a trusted server-side context, equating it to POST /v1/event. That verb+resource+scope framing separates it cleanly from siblings like list_events, get_analytics, and simulate_tap.

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 the alternative ('Apps should send events with the SDKs, not this tool') and the condition that flips behavior (confirm: true records; omit/false yields a preview). It also states the server-side/secret_key prerequisite that selects this tool over SDK usage.

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 say nothing about gating, dedupe or state; the description supplies all of it: a real event is injected into the receiving system, confirm: true is mandatory or nothing is sent, the X-Strait-Delivery id is preserved so receivers can de-duplicate, and the retry schedule restarts. It also discloses the two failure modes (409 duplicate/in-flight, immediate failure on paused webhooks).

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-loaded with a one-word operation class ('Write.'), then intent, then safety gate, then failure modes. Every sentence carries a distinct, actionable fact — no restatement of the title or schema.

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 two-parameter mutation with no output schema, the description covers the safety profile, the dedupe/idempotency behavior, the retry-reset side effect, and both error paths, plus the preview behavior when confirm is omitted. Nothing an agent needs to avoid a mistaken call 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% and both parameters are already documented in the schema ('true to send it; omit or false to preview' and 'the delivery id, from list_webhook_deliveries'), so the description adds little param-level detail beyond echoing the confirm gate. Baseline 3 applies when the schema carries the 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?

Specific verb + resource: 'Sends one past webhook delivery again, right away.' Scope is pinned down precisely ('one past delivery', 'to the webhook's current URL'), and 'For failed deliveries' separates it from the sibling test_webhook, which produces a synthetic event rather than replaying a real 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?

Explicit when ('For failed deliveries'), explicit when-not ('Refused (409) when already delivered or being sent right now'), and an explicit prerequisite ('A paused webhook must be turned back on first... otherwise the redelivery fails at once'). The only small gap is not naming test_webhook directly as the alternative for synthetic events.

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 destructiveHint/idempotentHint annotations by disclosing the concrete consequence (links stop working instantly), the fallback behavior (they still resolve on the strait.link address), the out-of-band DNS step, and the no-op preview when confirm is absent.

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 mutation marker and the core action, then layers consequence, follow-up, and the confirm gate in a short, dense block with no filler.

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

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

For a two-parameter destructive tool with no output schema, the description covers what changes, what survives, the required post-action DNS work, and the preview path — nothing an agent needs to call it safely 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%, and the schema already documents both confirm ('true to remove it; omit or false to preview') and hostname. The description restates the confirm behavior but adds no syntax or format detail 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 and resource ('Removes a custom link domain') and immediately explains the effect on links. An agent can distinguish it from add_domain/list_domains 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 operational context: use with confirm: true to actually remove, otherwise you get a preview, and it names the required follow-up DNS cleanup. It does not explicitly name sibling alternatives, which keeps it at a 4.

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 this is not read-only and not destructive, but the description adds substantial context beyond them: changes propagate to taps in about 30 seconds, confirm behaves as a preview without it, policy-disabled links are ineligible, and slug conflicts must be handled first.

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 front-loaded with the core action ('Write. Turns a paused link back on') and then layers in the confirm semantics and edge cases. It is dense but each sentence carries useful operational detail; the final list_links sentence is helpful but slightly auxiliary.

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, but for a non-destructive mutation tool the description covers the action, required confirmation, preview behavior, propagation timing, policy restrictions, and slug-conflict resolution. Nothing essential for correct invocation 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%, so the schema already documents both slug and confirm. The description still adds meaning beyond the schema by explaining that without confirm nothing changes and that the preview looks up the link among paused links, which clarifies the practical effect of the confirm flag.

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: 'Turns a paused link back on.' It clearly distinguishes this from siblings such as pause_link and deactivate_link by focusing on resuming a link that is already paused.

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 explicitly says confirm: true is required and that omitting it yields a preview. It also names blocking conditions: policy-disabled links cannot be resumed, and slug conflicts must be resolved by pausing or renaming the other active link. It even points to list_links with status: paused as the discovery path.

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, non-destructive, and openWorldHint=false; the description adds genuinely new context by confirming it 'works offline' and by specifying the return shape (Markdown sections with URLs). It stops short of noting result caps, ranking behavior, or doc staleness, which would be the remaining useful disclosures.

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 verb and corpus, followed by return format and the offline property. The long parenthetical topic list earns its space because it doubles as query vocabulary an agent can mine for keyword selection.

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 supplies the return shape and the offline behavior, which is enough to call the tool safely. Minor gaps remain around how many results are meaningful, query phrasing tips, and whether offline docs can be stale.

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 50%: limit is documented (default 4, max 10) but the required 'query' parameter has no description at all. The description implies query is a topic/keyword string via the coverage list but adds no syntax, phrasing, or ranking guidance, so it does not compensate for the gap.

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 ('Search the Strait documentation') and enumerates the topical coverage so an agent knows exactly what corpus is searched. Return format ('closest-matching sections as Markdown with their URLs') is stated up front, and the resource (docs) is clearly distinct from sibling search_links.

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 coverage list plus the 'works offline' note give a clear context for when to reach for this tool (documentation/how-to questions rather than workspace data). It does not explicitly name an exclusion such as 'for link data, use search_links or list_links', so routing between search_docs and search_links 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 cover readOnly/idempotent/non-destructive, so repeating "Read-only" earns nothing; however the description adds genuine context beyond the annotations: it discloses the auth requirement (owner/admin secret key) and the data source (workspace links export). The note that status: all surfaces paused/inactive links further clarifies result scope.

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 capability then modes then examples then access requirement; nothing is padded. The opening "Read-only." is largely redundant with readOnlyHint, a minor waste.

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

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

For a read-only search tool with full schema coverage and no output schema, the description covers capability, both query modes, result scope, and the auth prerequisite an agent must know before calling. Nothing material is left for the agent to infer.

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 by mapping the free-text query to the five searched fields and by framing tag/campaign as exact-match alternatives to the text search, which helps an agent choose between parameters rather than guess.

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 (finds) plus the resource (links) and enumerates the exact searchable fields: slug, title, destination/longUrl, campaign, tags. It also distinguishes the two search modes (free text vs. exact tag/campaign), which differentiates it from list_links, get_link and check_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?

Concrete example intents ("which links point at /summer", "every link tagged diwali", "links in the spring campaign") give the agent clear triggers. It does not explicitly name a sibling to use instead when a single link is already known (get_link) or when an unfiltered listing is wanted (list_links), so routing guidance is strong but not exhaustive.

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, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: no analytics recording and no billing impact, plus an enumeration of the decision outcomes returned. It doesn't explain the response shape in more detail, but that's minor here.

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 outcome list, then the key 'nothing recorded or billed' reassurance and the ua hint. No 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?

With no output schema, the description usefully enumerates the possible decision outcomes, which compensates well. The remaining gap is the url/slug selection rule, which an agent must infer from the schema alone.

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 all three parameters. The description only restates that ua is a preset or raw User-Agent, mirroring the schema. It misses a chance to clarify the url-vs-slug relationship, which the schema does not state explicitly.

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?

Specific verb and resource: 'Dry-run one tap on a link' with the outcomes it evaluates (redirect, in-app-browser escape page, store, preview card). It's clearly distinguishable from siblings in spirit, but it never names near-neighbors like trace_tap or check_link to disambiguate.

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 dry-run framing and 'Nothing is recorded or billed' imply the testing use case, but there's no explicit when-to-use or when-not-to-use, and no mention of trace_tap (the likely live-tracing alternative) or check_link. Usage is inferred rather than stated.

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: declares the event is a 'ping', bypasses paused state, is not stored or retried, changes nothing in Strait, and returns acceptance status, HTTP status and timing but never the response body. That is exactly the side-effect/side-channel detail an agent needs before firing an outbound request.

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-loaded with 'Write.' to signal mutation, then one dense sentence where every clause (pause bypass, no storage/retry, return fields, no body) carries information. The trailing id-sourcing clause is slightly cryptic but still 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?

No output schema exists, and the description compensates by enumerating the return values (accepted, HTTP status, elapsed time, not body). For a single-param, side-effecting call, nothing an agent needs in order 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% and the single param is documented in the schema, so baseline is 3; the description adds value by explaining where to source webhookId (list_webhook_deliveries without webhookId). It doesn't add format constraints, but the schema already carries the UUID pattern.

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 ('Sends one test event (event: ping) to a webhook') with scope qualifiers ('right now, even if it is paused'). It is clearly distinguishable from siblings like redeliver_webhook_delivery and list_webhooks.

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 a clear use context (test/verify a webhook receiver) and a prerequisite pointer for the id ('Get the id from list_webhook_deliveries without webhookId'). It does not explicitly contrast with redeliver_webhook_delivery, which is the nearest alternative, 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/non-destructive, so the bar is lower, but the description still adds real value: it discloses that the simulation records nothing, that the token path reads from the straitlink.in demo rather than the caller's own links, and that the output is one row per channel. It omits auth requirements and behavior when multiple of slug/url/token are supplied.

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 purpose, then the two modes in parallel structure. The parenthetical channel list is long but earns its place by communicating the breadth of the simulation, and 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?

There is no output schema, yet the description compensates by describing the return shape (one row per channel with decision, destination, and reason) and by explaining both input modes and their data sources. What remains unstated — mutual exclusivity of the params and error behavior — is minor for a read-only tool whose annotations cover the safety profile.

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 67% and both slug and token already carry descriptions, so the schema does most of the work. The description adds the useful framing that slug/url select the simulation path while token selects the live-trace path and corresponds to the 'st' value of a demo link, but says nothing about the undocumented 'url' parameter or precedence among the three optional params.

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 ('Explain where taps on a link go') and cleanly splits the tool into two distinct modes: a channel-walk simulation from a slug/url, and a read of a real Live Tap Trace from a token. It does not, however, differentiate itself from the sibling 'simulate_tap', which appears to cover adjacent ground, leaving the agent to infer the boundary.

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 between input modes ('With slug or url: ...' vs 'With token: ...') and gives the key selection signal that the token form is for a demo trace. It also clarifies the simulation is non-recording, distinguishing it from inspecting real traffic. It stops short of naming when to prefer this over simulate_tap or list_taps.

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?

Discloses behavior well beyond the annotations: the preview-vs-apply contract, that taps follow within ~30 seconds, that paused links serve a 'link not found' page, that AUP-disabled links are permanently un-reactivatable, and that null clears expiry fields. These are consequence details an agent could not infer from destructiveHint/idempotentHint alone.

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-loaded with the verb and affected fields, and nearly every sentence carries a distinct operational rule. It reads as one dense run-on paragraph, so the confirm/preview rule and the isActive rule are harder to scan than a short structured list would be.

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 9-parameter mutation tool with no output schema and no annotation detail, this covers nearly everything needed: preview behavior, null semantics, propagation delay, and failure modes. Minor gaps remain on merge-vs-replace semantics for tags/title and whether changing longUrl triggers revalidation.

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

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

With schema coverage at only 33%, the description compensates by defining the tri-state semantics of confirm (apply vs preview), the meaning of null for expiresAt/expiredAction/expiredUrl, and the exclusivity rule for isActive. None of these semantics are stated in 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?

Opens with a specific verb and resource ('Change a link') and immediately enumerates the mutable surface: destination, title, tags, expiry, and active state. It is clearly a mutation tool, but it never distinguishes itself from the sibling pause_link / resume_link / deactivate_link tools that overlap with its isActive behavior.

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 strong conditional guidance inside the tool: confirm: true applies the change, omitting it yields a preview to show the user first, and it names preconditions such as renaming or pausing a conflicting active link. It stops short of routing the agent to pause_link/resume_link for the simple active-state cases those siblings exist for.

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