Skip to main content
Glama

QuantApe Markets

by com.quantape
OverviewDiscussionsAdmin

cluster_context

Read-only

What happened recently to a ticker's peers: the cluster's move over the last 5 or 20 days (raw, market and residual), plus the news, earnings reactions, earnings-call guidance, price-mover explanations and themes that name its members. Give a symbol (its cluster; share classes are one company) or a cluster_id from graph_neighbors. Mega-caps and other names without a tight cluster get their closest residual-correlation peers instead (peers.kind = 'neighbors'). Peers are the ticker's residual-correlation cluster: stocks that move together once the market is removed. move is the cluster's equal-weight average in percent over the last 5 or 20 sessions: raw_* is the plain price move, market_* is SPY's, and residual_* is the move left after removing the market (the cluster-specific part); move.members has each member's own figures. Every news, earnings, transcript, mover and theme item cites a member symbol and a date. The optional digest (include_digest) is an LLM summary constrained to the cluster's members, each bullet citing members and a date; it may add latency, not cost. With mode 'peers' (symbol input only) the peers are instead the stocks whose residual moves track the ticker most closely (positive residual correlation over the past year, listed in peers.corr, with the ticker's leaf cluster as peers.theme): move is then the peers-only mean, move.symbol the ticker's own move and move.divergence_5d / _20d the ticker minus its peers, in percentage points. All of it is descriptive, not a recommendation. Free within your daily allowance (anonymous 5/day by IP, signed-in users 10/day, power users 50/day); beyond that $0.03 per call via x402 (USDC), with or without the digest.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysNoLook-back window in days: 5 (default) or 20.
modeNoSymbol input only. 'cluster' (default): the ticker's residual-correlation cluster. 'peers': the ticker plus the stocks whose residual moves track it most closely (with peers.corr), the peers' mean move, the ticker's own move and its divergence from them.
symbolNoTicker symbol, e.g. RGTI. Give this or cluster_id, not both.
cluster_idNoCluster id from graph_neighbors. Give this or symbol, not both.
include_digestNoAlso attach the LLM digest (default false). Slower; a failed digest comes back as digest: null with digest_status, never as an error.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysYes5 or 20 calendar days behind news, earnings, transcripts, movers and themes
moveYes
newsYes
as_ofYesYYYY-MM-DD the window ends on
peersNosymbol input only: the peers the payload covers (absent for cluster_id input)
countsYes
digestNoinclude_digest only: LLM summary constrained to the member symbols of the peers; null when it could not be produced
moversYes
symbolNoThe ticker asked about (symbol input only)
themesYes
clusterYesThe symbol's cluster, or null when it is in no tight cluster (then see peers)
earningsYes
transcriptsYes
digest_modelNoinclude_digest only
digest_statusNoinclude_digest only

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedInput schema / properties / mode
      Added value: +{
+  "description": "Symbol input only. 'cluster' (default): the ticker's residual-correlation cluster. 'peers': the ticker plus the stocks whose residual moves track it most closely (with peers.corr), the peers' mean move, the ticker's own move and its divergence from them.",
+  "enum": [
+    "cluster",
+    "peers"
+  ],
+  "type": "string"
+}
    • changedOutput schema / properties / digest / description
      Previous value: -"include_digest only: LLM summary constrained to the member symbols of the peers (cluster or neighbourhood); null when it could not be produced"New value: +"include_digest only: LLM summary constrained to the member symbols of the peers; null when it could not be produced"
    • addedOutput schema / properties / move / properties / divergence_20d
      Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}
    • addedOutput schema / properties / move / properties / divergence_5d
      Added value: +{
+  "description": "peers mode only: the symbol's residual move minus the peers' mean, in percentage points",
+  "type": [
+    "number",
+    "null"
+  ]
+}
    • addedOutput schema / properties / move / properties / members / items / properties / corr
      Added value: +{
+  "description": "peers mode only: residual correlation with the asked symbol",
+  "type": [
+    "number",
+    "null"
+  ]
+}
    • addedOutput schema / properties / move / properties / symbol
      Added value: +{
+  "additionalProperties": {},
+  "description": "peers mode only: the asked symbol's own move (the group figures above exclude it)",
+  "properties": {
+    "raw_20d": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "raw_5d": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "residual_20d": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "residual_5d": {
+      "type": [
+        "number",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "residual_5d",
+    "residual_20d",
+    "raw_5d",
+    "raw_20d"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / peers / properties / corr
      Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "description": "peers only: peer ticker -> its residual correlation with the asked symbol over 250 sessions (market removed), most correlated first",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
    • changedOutput schema / properties / peers / properties / kind / description
      Previous value: -"'cluster': the symbol's peer group (a leaf of the cluster hierarchy); 'industry': no tight cluster, so its industry peers ranked by residual correlation; 'neighbors': the symbol plus its closest residual-correlation peers (industry unknown)"New value: +"'peers' (mode peers): the symbol plus the stocks whose residual moves track it most closely, r >= min_corr, ranked in peers.corr; 'cluster': the symbol's peer group (a leaf of the cluster hierarchy); 'industry': no tight cluster, so its industry peers ranked by residual correlation; 'neighbors': the symbol plus its closest residual-correlation peers (industry unknown)"
    • changedOutput schema / properties / peers / properties / kind / enum
      Previous value: -[
-  "cluster",
-  "industry",
-  "neighbors"
-]New value: +[
+  "cluster",
+  "industry",
+  "neighbors",
+  "peers"
+]
    • addedOutput schema / properties / peers / properties / min_corr
      Added value: +{
+  "description": "peers only: the minimum residual correlation of a peer",
+  "type": "number"
+}
    • addedOutput schema / properties / peers / properties / theme
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "properties": {
+        "id": {
+          "type": "number"
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "size": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "id",
+        "label",
+        "size"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "peers only: the symbol's leaf cluster, for context, or null when it is in none"
+}
  2. Added

TDQS

A4.5/5.0
Behavior5/5

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

With only readOnlyHint=true in annotations, the description carries the rest and does so richly: it discloses the per-day allowance tiers (5/10/50), the $0.03 x402 overage, that the digest adds latency but not cost, and that a failed digest returns digest: null with digest_status rather than an error. These are exactly the behavioral traits annotations cannot express.

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

Conciseness3/5

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

It is front-loaded correctly, but it is a single dense wall of text that sprawls well past the point of necessity. Much of the field-level explanation (move.raw_*, residual_*, peers.corr, peers.kind) duplicates the output schema, which already exists, so those sentences do not fully earn their place.

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

Completeness5/5

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

For a read-only analytics tool with a rich output schema, it covers everything an agent needs: inputs, mode semantics, cost/allowance, latency, and digest failure handling. Nothing required 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.

Parameters4/5

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 real meaning: it explains what days (5 vs 20 sessions) means, what mode='peers' changes about the output, and the symbol/cluster_id mutual exclusivity. It goes modestly beyond the schema rather than merely restating it.

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

Purpose5/5

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

The description opens with a specific verb+resource: it returns what recently happened to a ticker's peers — cluster moves (raw/market/residual), news, earnings reactions, guidance, movers and themes. It distinguishes itself from siblings by explicitly pointing to graph_neighbors as the source of cluster_id, so an agent can tell it apart from get_stock_insights or graph_neighbors 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.

Usage Guidelines4/5

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

It clearly states input routing (give a symbol or a cluster_id from graph_neighbors, not both), explains the cluster vs peers mode selection, and notes the fallback for mega-caps without a tight cluster. It stops short of explicitly contrasting when to prefer this over siblings like get_stock_insights, but the operational context is strong.

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

All QuantApe Markets toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources