hn-tech-signal-mcp

Overview Schema Source Related Servers Discussions Admin

hn_discussion

Read-onlyIdempotent

Retrieves the comment thread under a HackerNews story to show what is actually argued, including counter-arguments and practitioner caveats.

Instructions

Read the comment thread under a HackerNews story.

Where hn_top_stories and hn_search tell you what is being discussed, this tells you what is actually being argued — the counter-arguments, the practitioner caveats, the "we tried this in production" replies that carry the real signal. Algolia can search comment text but does not return thread structure, so this is the only way to see who replied to whom.

Get a story_id from hn_top_stories or hn_search first.

Comments are walked breadth-first, so the highest-ranked top-level comments come back first. Deleted and flagged comments are skipped. Popular threads run to several hundred comments and each one costs a request upstream, so both depth and total count are capped — check the 'truncated' flag to see whether the thread was cut short.

Args: params (HnDiscussionInput): - story_id (int): HackerNews item ID - max_depth (int): Reply nesting levels (1–4, default 2) - max_comments (int): Total comment budget (1–100, default 25) - text_chars (int): Per-comment text truncation (100–2000)

Returns: str: JSON with story{}, total_comments (as reported by HN), fetched_comments, truncated, comments[]. Each comment: id, by, posted, text, reply_count, replies[] (same shape, nested).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description
`story`	Yes
`comments`	Yes
`truncated`	Yes	True if depth or comment budget cut the thread short
`fetched_at`	Yes
`story_text`	Yes
`total_comments`	Yes	As reported by HN
`fetched_comments`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv0.5.0Sep 30, 2026

addedOutput schema / $defs

Added value: +{
+  "HnComment": {
+    "additionalProperties": false,
+    "properties": {
+      "by": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "By"
+      },
+      "id": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Id"
+      },
+      "posted": {
+        "title": "Posted",
+        "type": "string"
+      },
+      "replies": {
+        "items": {
+          "$ref": "#/$defs/HnComment"
+        },
+        "title": "Replies",
+        "type": "array"
+      },
+      "reply_count": {
+        "description": "Direct replies upstream, fetched or not",
+        "title": "Reply Count",
+        "type": "integer"
+      },
+      "text": {
+        "title": "Text",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "by",
+      "posted",
+      "text",
+      "reply_count",
+      "replies"
+    ],
+    "title": "HnComment",
+    "type": "object"
+  },
+  "HnStory": {
+    "additionalProperties": false,
+    "properties": {
+      "by": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "By"
+      },
+      "comments": {
+        "title": "Comments",
+        "type": "integer"
+      },
+      "hn_link": {
+        "title": "Hn Link",
+        "type": "string"
+      },
+      "id": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Id"
+      },
+      "posted": {
+        "description": "UTC timestamp, or 'unknown'",
+        "title": "Posted",
+        "type": "string"
+      },
+      "score": {
+        "title": "Score",
+        "type": "integer"
+      },
+      "title": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Title"
+      },
+      "type": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "'story' or 'job'",
+        "title": "Type"
+      },
+      "url": {
+        "description": "Linked article, or the HN item itself for Ask HN",
+        "title": "Url",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "type",
+      "title",
+      "url",
+      "score",
+      "comments",
+      "by",
+      "posted",
+      "hn_link"
+    ],
+    "title": "HnStory",
+    "type": "object"
+  }
+}

addedOutput schema / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / comments

Added value: +{
+  "items": {
+    "$ref": "#/$defs/HnComment"
+  },
+  "title": "Comments",
+  "type": "array"
+}

addedOutput schema / properties / fetched_at

Added value: +{
+  "title": "Fetched At",
+  "type": "string"
+}

addedOutput schema / properties / fetched_comments

Added value: +{
+  "title": "Fetched Comments",
+  "type": "integer"
+}

removedOutput schema / properties / result

Removed value: -{
-  "title": "Result",
-  "type": "string"
-}

addedOutput schema / properties / story

Added value: +{
+  "$ref": "#/$defs/HnStory"
+}

addedOutput schema / properties / story_text

Added value: +{
+  "title": "Story Text",
+  "type": "string"
+}

addedOutput schema / properties / total_comments

Added value: +{
+  "description": "As reported by HN",
+  "title": "Total Comments",
+  "type": "integer"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True if depth or comment budget cut the thread short",
+  "title": "Truncated",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "fetched_at",
+  "story",
+  "story_text",
+  "total_comments",
+  "fetched_comments",
+  "truncated",
+  "comments"
+]

changedOutput schema / title

Previous value: -"hn_discussionOutput"New value: +"HnDiscussionOutput"

Addedv0.3.0Jul 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those hints: breadth-first comment walking, skipped deleted/flagged comments, upstream request cost, and capped depth/comment count with a 'truncated' flag to detect cut-off threads.

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 description is front-loaded with purpose, sibling differentiation, and prerequisites before moving into behavior and arguments. It is somewhat verbose, and the Returns section partially duplicates the available output schema, but most sentences 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, idempotent thread-fetching tool with an output schema, the description supplies all needed context: prerequisite source for story_id, traversal behavior, truncation semantics, and parameter limits. Nothing critical is missing for correct invocation.

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 reported as 0%, so the description carries the burden and does so by listing story_id, max_depth, max_comments, and text_chars with ranges, defaults, and practical meaning. It adds source guidance for story_id and interpretation for max_depth, though some details mirror the schema's own property descriptions.

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 states a specific verb and resource: read the comment thread under a HackerNews story. It explicitly distinguishes this tool from hn_top_stories and hn_search, and explains that it returns thread structure rather than just comment text.

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 prerequisites ('Get a story_id from hn_top_stories or hn_search first') and contrasts the tool with siblings by saying Algolia can search comment text but does not return thread structure. The agent knows exactly when this tool is the right choice.

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

Deploy Server