ShortsIntel

Read a research

get_research

Read-onlyIdempotent

Use when you have a research or breakdown run id and want its digest, videos, creators, hashtags or sounds, filtered or sorted (e.g. TikTok only, over 100k views, best outlier first). Not for collecting new data: use research or breakdown (charged, takes minutes). For a Run still running, use get_run. Price: Free. aspect picks the read (default videos). Each filter names the aspects that take it; others are refused. Numbers are as the research saw them; as_of=latest for the newest.

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": {
      "run_id": "<run_id>"
    },
    "name": "get_research"
  }
}

Input Schema

Name	Required	Description
`sort`	No	asc or desc (default). Aspects: all but digest
`as_of`	No	run (default) is what the research saw, frozen; latest is the newest this API holds, and is uneven until you refresh the research
`limit`	No	Page size. Aspects: all but digest
`sound`	No	Sound id. Aspects: videos
`aspect`	No	What to read: digest (the synthesis), videos (the shortlist), creators, hashtags or sounds. Defaults to videos.
`offset`	No	Rows to skip. Aspects: all but digest
`run_id`	Yes	The run id a previous research or breakdown call returned
`creator`	No	Creator id or handle. Aspects: videos
`hashtag`	No	Keeps videos carrying this hashtag. Aspects: videos
`end_date`	No	ISO date; keeps videos posted at or before it. Aspects: videos
`order_by`	No	videos: rank (default), outlier, views, posted_at. creators: outlier (default), median_views, followers, video_count, views. hashtags and sounds: video_count (default) or views. Not for digest.
`max_views`	No	Keeps videos with at most this many views. Aspects: videos
`min_views`	No	Keeps videos with at least this many views. Aspects: videos
`platforms`	No	Keeps rows from these platforms. Aspects: all but digest
`start_date`	No	ISO date; keeps videos posted at or after it. Aspects: videos
`max_followers`	No	Keeps creators with at most this many followers. Aspects: creators
`min_followers`	No	Keeps creators with at least this many followers. Aspects: creators

Output Schema

Name	Required	Description
`run`	No
`mode`	No
`as_of`	No	Which snapshots the numbers come from.
`items`	No
`limit`	No
`total`	No	Rows matching the filters, before `limit` and `offset`.
`digest`	No
`intent`	No
`offset`	No
`result`	No	What a research recorded about itself.
`coverage`	No
`keywords`	No
`poll_url`	No
`lift_tables`	No	Lift tables computed in code over the analysed videos.
`digest_version`	No
`keyword_rationale`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 6, 2026

changedInput schema / properties / run_id / description

Previous value: -"The run id a previous research call returned"New value: +"The run id a previous research or breakdown call returned"

Changed16 schema fields changedNov 5, 2026

changedInput schema / properties / limit / description

Previous value: -"Page size. Aspects: videos, creators, hashtags, sounds"New value: +"Page size. Aspects: all but digest"

changedInput schema / properties / offset / description

Previous value: -"Rows to skip. Aspects: videos, creators, hashtags, sounds"New value: +"Rows to skip. Aspects: all but digest"

changedInput schema / properties / platforms / description

Previous value: -"Keeps rows from these platforms. Aspects: videos, creators, hashtags, sounds"New value: +"Keeps rows from these platforms. Aspects: all but digest"

changedInput schema / properties / sort / description

Previous value: -"asc or desc (default). Aspects: videos, creators, hashtags, sounds"New value: +"asc or desc (default). Aspects: all but digest"

removedOutput schema / properties / items / anyOf

Removed value: -[
-  {
-    "items": {
-      "$ref": "#/properties/run"
-    },
-    "type": "array"
-  },
-  {
-    "items": {
-      "$ref": "#/properties/run"
-    },
-    "type": "array"
-  },
-  {
-    "items": {
-      "$ref": "#/properties/run"
-    },
-    "type": "array"
-  },
-  {
-    "items": {
-      "$ref": "#/properties/run"
-    },
-    "type": "array"
-  }
-]

addedOutput schema / properties / items / items

Added value: +{
+  "$ref": "#/properties/run"
+}

addedOutput schema / properties / items / type
```
Added value: +"array"
```

removedOutput schema / properties / limit / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  }
-]

addedOutput schema / properties / limit / type
```
Added value: +"integer"
```

addedOutput schema / properties / mode

Added value: +{
+  "enum": [
+    "keywords",
+    "creators"
+  ],
+  "type": "string"
+}

removedOutput schema / properties / offset / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  }
-]

addedOutput schema / properties / offset / type
```
Added value: +"integer"
```
changedOutput schema / properties / run / additionalProperties
```
Previous value: -trueNew value: +{}
```
removedOutput schema / properties / run / properties
```
Removed value: -{}
```

removedOutput schema / properties / total / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  },
-  {
-    "type": "integer"
-  }
-]

addedOutput schema / properties / total / type
```
Added value: +"integer"
```

Changed1 schema field changedNov 4, 2026
- addedOutput schema / properties / poll_url
```
Added value: +{
+  "format": "uri",
+  "type": "string"
+}
```

Changed1 schema field changedNov 4, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "as_of": {
+      "description": "Which snapshots the numbers come from.",
+      "enum": [
+        "run",
+        "latest"
+      ],
+      "type": "string"
+    },
+    "coverage": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "digest": {
+      "$ref": "#/properties/run"
+    },
+    "digest_version": {
+      "type": "integer"
+    },
+    "intent": {
+      "type": "string"
+    },
+    "items": {
+      "anyOf": [
+        {
+          "items": {
+            "$ref": "#/properties/run"
+          },
+          "type": "array"
+        },
+        {
+          "items": {
+            "$ref": "#/properties/run"
+          },
+          "type": "array"
+        },
+        {
+          "items": {
+            "$ref": "#/properties/run"
+          },
+          "type": "array"
+        },
+        {
+          "items": {
+            "$ref": "#/properties/run"
+          },
+          "type": "array"
+        }
+      ]
+    },
+    "keyword_rationale": {
+      "type": "string"
+    },
+    "keywords": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "lift_tables": {
+      "$ref": "#/properties/run",
+      "description": "Lift tables computed in code over the analysed videos."
+    },
+    "limit": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        }
+      ]
+    },
+    "offset": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        }
+      ]
+    },
+    "result": {
+      "$ref": "#/properties/run",
+      "description": "What a research recorded about itself."
+    },
+    "run": {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    },
+    "total": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "integer"
+        }
+      ],
+      "description": "Rows matching the filters, before `limit` and `offset`."
+    }
+  },
+  "type": "object"
+}

First observedNov 2, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description still adds genuinely new behavior: it is free, aspect selects which read happens, non-applicable filters are refused rather than ignored, and returned numbers are frozen as the research saw them. The one remaining gap is that it doesn't say what happens when limit/offset paging runs past the end of the result set.

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 when-to-use sentence is front-loaded, followed by exclusions, price, and a compact paragraph on aspect/filter interaction; nothing is padded. It is slightly telegraphic in places ('Price: Free.', fragmentary clauses), but each line carries distinct information.

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 17-parameter read tool with a full output schema and rich annotations, the description covers everything the agent still needs: routing versus siblings, the aspect-driven filter refusal rule, default sort/aspect behavior, and pricing. Return-value details are correctly left to the output schema.

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, and the description earns the step up by explaining the cross-parameter rule that the chosen aspect determines which filters are accepted and others are refused, plus the default (aspect=videos) and the meaning of as_of=latest as uneven until refreshed. That constraint is not obvious from per-parameter schema text alone.

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 opening sentence states a specific verb and resource (read the results of a research/breakdown run) and enumerates the readable aspects (digest, videos, creators, hashtags, sounds) plus filtering/sorting with concrete examples. An agent can distinguish it from research, breakdown and get_run 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.

Usage Guidelines5/5

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

It gives explicit when-to-use (you already have a run id) and explicit when-not-to-use, naming the alternatives and the reasons that select them: research/breakdown for new data (charged, takes minutes) and get_run for a run still in progress. No routing inference is left to the agent.

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

All ShortsIntel tools Inspect

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

Need Help?