splithub_links

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

With no annotations, the description carries the full burden. It discloses useful behavior (clicks are counted, stats window and breakdowns, weighting of traffic), but not whether pause/resume are reversible, whether delete is permanent and destroys click history, what permissions are needed, or what an error looks like. For a tool with destructive actions and zero annotation coverage, that is a material omission.

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?

Dense but purposeful: the resource and its capability lead, then each action with its parameters, then the scope exclusion last. No sentence is redundant with the schema, and the telegraphic style keeps seven operations readable in one paragraph.

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?

Seven parameters, no annotations, no output schema, and mutation actions including delete — the description covers action semantics well but leaves an agent without knowledge of auth prerequisites, delete irreversibility, pagination on the list action, or what create returns (the new slug/id). Adequate but with clear gaps for a multi-mode mutation tool.

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 only 43%, so compensation matters. The description goes beyond the schema by constraining slug to '3-32 letters, digits, - _; random when omitted', requiring 'full http(s) URLs' and 'one per URL' weights, and mapping each parameter to the action that consumes it. It adds nothing for `name` or `description` beyond their schema maxLength.

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 opening sentence names the specific resource (short links / weighted split redirects with click counting) and the second enumerates the exact operations available. An agent can tell this is the SplitHub link-management tool, but nothing distinguishes it from siblings like splithub_analytics or splithub_results, which also surface click data.

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?

Per-action guidance is strong: 'action list (default)' sets the default, and each mode states its scope (stats = 30 days, per destination/country/device/referrer/unique). It even draws a when-NOT boundary — 'Targeting by country, device or a flow is done in the dashboard' — but never names an alternative sibling tool for related click analytics.

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