Unilytics MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

aeo_cluster_by_urls

Read-only

Cluster prompts by shared Google SERP URLs and assign each cluster a page with rank-weighted mapping, so related queries are grouped and routed to relevant content.

Instructions

Cluster prompts by shared Google SERP URLs, then assign each cluster a page.

Greedy centroid assignment on an ABSOLUTE shared-URL count (no transitive chaining). A join on
exactly one shared URL is allowed only if that URL is specific (low corpus document frequency),
is not a generic hub host, and the prompt is not a brand comparison — and such joins are NEVER
auto-accepted (they come back with needs_review=true). Query-drift SERPs are quarantined.
Page assignment is rank-weighted: a rank-1 brand hit outweighs a rank-10 one.

items = [{id, text, impressions?, serp: [{url, rank, near_miss}], serp_urls?: [...] (legacy),
          citation_urls?: [...] (a SEPARATE signal — never joins clusters), spell?, mapped_pages?}]
config = per-project {brand:{domain, owned_domains[]}, competitors[], cluster:{T, one_shared_max_df, hub_hosts,...},
         signals:{a_min_hits, a_high_confidence_max_rank}} — nothing client-specific is hardcoded.
         brand.owned_domains = the brand's other domains (e.g. "example.com" for a site on blog.example.com).

At most 80 items per call, each text up to 300 characters.

Returns {clusters (with prompt_ids), assignments (prompt_id → cluster_id, mapped page, signal, confidence),
n_items, n_clusters, needs_review, n_quarantined, caveat}. A mapped brand page is a path ("/pricing") on the
brand.domain host, or a full URL on any other host of brand.domain or brand.owned_domains
("https://docs.example.com/setup").

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "items": "<items>"
    },
    "name": "aeo_cluster_by_urls"
  }
}

Input Schema

Name	Required	Description	Default
`items`	Yes
`config`	No
`page_inventory`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Aug 2, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description then adds genuinely valuable behavior: absolute (non-transitive) shared-URL counting, single-URL joins returning needs_review=true, quarantine of query-drift SERPs, and rank-weighted page assignment. With annotations in place the bar is lower, but these disclosures are substantive and materially exceed what the structured fields provide.

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

Conciseness4/5

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

The core action and the algorithm rules are front-loaded, and the inline pseudo-schema for items and config packs a lot into little space. It is dense but almost every line carries operational meaning; the mapped-page host/path explanation is slightly verbose but resolves a real ambiguity.

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

Completeness4/5

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 naming the returned fields (clusters, assignments, n_items, n_clusters, needs_review, n_quarantined, caveat) and explaining what a mapped page means. For a high-complexity nested-input tool this is nearly complete; the unmentioned page_inventory parameter is the one real hole.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does so for two of three: items is laid out field by field (id, text, impressions, serp url/rank/near_miss, legacy serp_urls, separable citation_urls, spell, mapped_pages), and config's brand, competitors, cluster thresholds, and signals are enumerated with the note that nothing client-specific is hardcoded. The third parameter, page_inventory, is never mentioned anywhere in the description or schema, which keeps this below a 5.

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

Purpose4/5

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

The first sentence states a specific verb and resource: cluster prompts by shared Google SERP URLs, then assign each cluster a page. That is far more precise than a restatement of the name. It never names or contrasts with the sibling aeo_cluster_prompts, so the agent must infer which clustering tool to pick.

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

Usage Guidelines3/5

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

Operationally useful constraints are present (at most 80 items per call, each text up to 300 characters, citation_urls never joins clusters), which tells the agent how to prepare input. However, there is no explicit statement of when to choose this tool over aeo_cluster_prompts or aeo_serp_urls, and no preconditions beyond the size limits. Usage is implied rather than routed.

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

Deploy Server