Provides search capabilities for Hacker News stories, comments, and users via Algolia's Hacker News Search API, supporting queries, filtering, and pagination.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hacker-news-mcp Search Ask HN for pain points about SaaS pricing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A TypeScript MCP server for Hacker News with a practical founder-research layer on top.
It still gives you the raw Hacker News primitives you expect, but it also helps with the things indie developers actually care about:
finding Show HN launches in a niche
mining Ask HN threads for pain points
summarizing long discussions quickly
extracting product, launch, and monetization signals
comparing multiple launches for patterns
This project uses the official Hacker News API plus Algolia's Hacker News Search API. There are no external AI APIs, no database, and no browser automation.
search
getStory
getStoryWithComments
getStories
getComment
getComments
getCommentTree
getUser
getUserSubmissions
findShowHN
findAskHN
summarizeThread
extractStartupInsights
compareLaunches
Related MCP server: HN-MCP
findShowHNSearch Show HN posts by keyword with optional filters.
Inputs:
query: string
page?: number
hitsPerPage?: number
minPoints?: number
minComments?: number
dateFrom?: string
dateTo?: string
Returns normalized results with:
id
title
url
author
points
numComments
createdAt
hnUrl
textPreview
findAskHNSearch Ask HN posts for pain points and demand signals.
Inputs are the same as findShowHN.
summarizeThreadSummarize a story and comment thread using deterministic heuristics.
Inputs:
storyId: number
maxDepth?: number
maxComments?: number
Returns:
story metadata
key discussion themes
notable pros
notable cons
repeated questions
feature requests
sentiment snapshot
top comments used
extractStartupInsightsExtract founder-relevant signals from either one thread or a query.
Inputs:
storyId?: number
query?: string
sourceType?: "show" | "ask" | "story" | "comment"
maxItems?: number
Returns:
targetUsers
painPoints
alternativesMentioned
objections
monetizationSignals
launchFeedback
opportunities
risks
recommendedFollowups
lowConfidenceAreas
compareLaunchesCompare multiple Show HN launches.
Inputs:
storyIds: number[]
Returns:
launch-by-launch comparison
title style patterns
topic categories
common praise
common criticism
likely traction drivers
skipped IDs when some stories cannot be loaded
"Find Show HN launches about CRM tools for founders with at least 30 comments."
"Search Ask HN for pain points around bookkeeping automation."
"Summarize HN thread 43130155 with maxDepth 2 and maxComments 40."
"Extract startup insights from story 43130155."
"Analyze Ask HN results for manual invoicing and return pain points plus monetization signals."
"Compare Show HN launches 43130155, 42302015, and 41806551."
Node.js 18+
npm
npm installnpm run buildnpm testnode dist/index.jsBuild the server first:
npm install
npm run buildThen point your MCP client at the compiled entrypoint:
/absolute/path/to/hacker-news-mcp/dist/index.jsReplace /absolute/path/to/... with the real path on your machine.
If your Codex setup supports local stdio MCP servers, add an entry that runs:
{
"mcpServers": {
"hacker-news-mcp": {
"command": "node",
"args": ["/absolute/path/to/hacker-news-mcp/dist/index.js"]
}
}
}This is the same pattern used by other local MCP clients: Codex launches the server process for you, so you do not need to manually keep node dist/index.js running in another terminal.
If you use Antigravity as an MCP client, configure hacker-news-mcp as a local stdio server with the same command:
{
"mcpServers": {
"hacker-news-mcp": {
"command": "node",
"args": ["/absolute/path/to/hacker-news-mcp/dist/index.js"]
}
}
}If Antigravity expects an explicit transport type, use:
{
"mcpServers": {
"hacker-news-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/hacker-news-mcp/dist/index.js"]
}
}
}Add this to your MCP config:
{
"mcpServers": {
"hacker-news-mcp": {
"command": "node",
"args": ["/absolute/path/to/hacker-news-mcp/dist/index.js"]
}
}
}type: "stdio"{
"mcpServers": {
"hacker-news-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/hacker-news-mcp/dist/index.js"]
}
}
}npxIf you publish the package later, the config can become:
{
"mcpServers": {
"hacker-news-mcp": {
"command": "npx",
"args": ["-y", "@devabdultech/hacker-news-mcp"]
}
}
}stdio MCP clientsThis server is intentionally simple:
transport: stdio
runtime: node
entrypoint: dist/index.js
If a client supports local MCP servers, you usually only need:
command: "node"
args: ["/absolute/path/to/hacker-news-mcp/dist/index.js"]
After changing the config:
Save the client configuration
Restart or reload the client
Ask the client to list tools or call findShowHN
You only need to rebuild the server when the code changes. You do not need to manually run the server in the background for normal client usage.
If you have never published a project before, this is the straightforward path.
Run:
npm run build
npm testOn GitHub:
Click New repository
Name it hacker-news-mcp
Leave it empty
Do not add a README, .gitignore, or license there
If this repo is not initialized yet:
git init -b main
git add .
git commit -m "Initial commit"Replace YOUR_USERNAME below:
git remote add origin https://github.com/YOUR_USERNAME/hacker-news-mcp.git
git push -u origin mainIf GitHub asks for authentication, use GitHub Desktop, the GitHub CLI, or a personal access token in your normal setup.
GitHub is free and easy.
npm publishing is separate.
Before publishing to npm, make sure:
the package name is available
your npm account can publish the chosen scope
the README examples match the final package name
Current package name:
@devabdultech/hacker-news-mcpIf that scope is not the one you want long-term, change it before publishing to npm.
If you delete .git and reinitialize, you lose:
previous commits
original remote links
old branch history
That is fine if you want a fresh public repo, but it is not reversible unless you backed up the old .git directory first.
Before publishing, check that you are not committing:
.env files
API keys
tokens
private config files
local logs
This repo currently ignores common env files and .omx/, which is good.
If your MCP clients still point at the old folder path, they will fail.
Use:
/absolute/path/to/hacker-news-mcp/dist/index.jsGitHub repo names and npm package names do not have to match, but confusion there is a classic self-own.
If you publish to npm later, keep the README install command aligned with the real package name.
src/
api/ Hacker News and Algolia API clients
analysis/ Normalization, heuristics, and founder-research logic
models/ Lightweight domain models
schemas/ Zod request schemas
services/ Thin orchestration layer for higher-level tools
index.ts MCP server registration and tool handlers
tests/ Basic analysis tests
dist/ Compiled outputMIT. See LICENSE.
Compare multiple Show HN launches and surface traction patterns
| Name | Required | Description | Default |
|---|---|---|---|
| storyIds | Yes | Array of Show HN story IDs to compare |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It states the tool 'compares' and 'surfaces traction patterns' but does not disclose any behavioral traits such as side effects, data modifications, or how the comparison is performed. This leaves the agent with an incomplete understanding of the tool's behavior.
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?
The description is a single efficient sentence that front-loads the main action. No wasted words.
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?
For a simple tool with one parameter and no output schema, the description gives the gist but lacks details on the output format or what exactly constitutes 'traction patterns'. The agent may need more context to decide if the tool is suitable.
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?
The input schema already provides a clear description for the only parameter (storyIds). With 100% schema coverage, the tool description adds minimal extra meaning. Baseline score of 3 is appropriate.
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 description clearly states the verb 'compare' and the resource 'Show HN launches', and specifies the result as 'surface traction patterns'. It differentiates from siblings like findShowHN or getStories by focusing on comparison, though 'traction patterns' is somewhat vague.
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?
The description implies usage when you have multiple Show HN story IDs to compare, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract founder-relevant product and business insights from HN data
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query to analyze matching posts | |
| storyId | No | Analyze a specific story thread | |
| maxItems | No | Maximum number of matching items to analyze | |
| sourceType | No | Which HN source shape to analyze | story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not state whether the tool is read-only, mutates data, requires authentication, or has rate limits. The agent has no behavioral context beyond the basic function.
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?
The description is a single concise sentence front-loaded with the key action ('Extract'). It has no wasted words, but could benefit from slightly more detail without sacrificing conciseness.
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?
With 4 parameters, no output schema, and no annotations, the description is too sparse. It does not explain the output format, how parameters interact, or edge cases. The agent lacks sufficient context to use the tool reliably.
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?
All 4 parameters are described in the input schema (100% coverage). The tool description adds no additional meaning beyond what the schema provides. Baseline 3 is appropriate as the schema does the heavy lifting.
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 description states the tool extracts 'founder-relevant product and business insights from HN data', which clearly identifies the verb and resource. However, it does not differentiate from sibling tools like 'search' or 'summarizeThread', which could overlap in functionality. The purpose is clear but lacks uniqueness.
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?
No guidance is provided on when to use this tool vs. alternatives. The description does not mention prerequisites, contexts, or exclusion cases. The agent is left without decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Ask HN posts for problem discovery and demand signals
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Result page | |
| query | Yes | Keyword or problem area to search for | |
| dateTo | No | Only include results on or before this date | |
| dateFrom | No | Only include results on or after this date | |
| minPoints | No | Minimum point score | |
| hitsPerPage | No | Number of items to return | |
| minComments | No | Minimum comment count |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full weight. It only states 'search' but does not disclose behavioral traits such as being read-only, auth requirements, rate limits, pagination limits, or what happens to results. The parameter descriptions partially help but overall transparency is low.
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?
The description is a single, front-loaded sentence. It is concise without extraneous words. However, it could be slightly more structured (e.g., first sentence for purpose, second for usage).
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?
The tool has 7 parameters, no output schema, and no annotations. The description fails to explain what the search results contain (e.g., titles, URLs, scores) or how pagination works. This is incomplete for a complex search 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 description coverage is 100%, so baseline is 3. The description adds some context ('problem discovery and demand signals') but does not elaborate on parameter behavior beyond what the schema provides. Value is marginal over schema.
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 description clearly identifies the tool as searching Ask HN posts, with a specific purpose of problem discovery and demand signals. This distinguishes it from sibling tools like findShowHN (which searches Show HN posts) and general search.
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?
No guidance is provided on when to use this tool versus alternatives like search or findShowHN. The description implies use for problem discovery but does not contrast with other tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Show HN launches by keyword with founder-friendly filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Result page | |
| query | Yes | Keyword or niche to search for | |
| dateTo | No | Only include results on or before this date | |
| dateFrom | No | Only include results on or after this date | |
| minPoints | No | Minimum point score | |
| hitsPerPage | No | Number of items to return | |
| minComments | No | Minimum comment count |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as rate limits, authentication requirements, or side effects. The description only states the basic function without additional context about tool behavior.
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?
The description is a single concise sentence with no wasted words. However, it is somewhat vague, and the term 'founder-friendly filters' is not elaborated, slightly reducing clarity.
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?
For a search tool with 7 parameters and no output schema, the description is too brief. It does not explain the return format, pagination, or how the filters work, leaving the agent with insufficient context for effective use.
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 100%, so baseline is 3. The description adds no additional meaning beyond the schema; 'founder-friendly filters' is vague and does not explain parameter semantics or usage patterns.
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 description clearly states the tool searches Show HN launches by keyword, using the specific verb 'Search' and resource 'Show HN launches'. It distinguishes from sibling 'findAskHN' which serves a different Hacker News section.
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?
The description implies usage for searching Show HN launches with founder-friendly filters, but does not explicitly state when to use this tool over alternatives like 'findAskHN' or 'search'. No exclusions or when-not-to-use guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single comment by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description accurately reflects a read operation; no annotations to contradict, but lacks detail on response format or post-fetch behavior.
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?
Single, clear sentence with no unnecessary words.
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?
For a simple single-ID fetch with no output schema, the description is sufficient and complete.
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 covers 100% of parameters; description adds no extra meaning beyond restating the purpose.
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?
Description clearly states the action (get), resource (comment), and scope (single by ID), distinguishing it from siblings like getComments and getCommentTree.
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?
No explicit guidance on when to use this tool vs alternatives; context is implied by sibling names but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments for a story
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The maximum number of comments to fetch | |
| storyId | Yes | The ID of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose any behavioral details (pagination, sorting, error handling, etc.). This is insufficient for a tool that may be called by an AI agent.
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?
Single sentence, front-loaded with key information. Could be expanded slightly but remains efficient.
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?
No output schema and no annotations; description is too minimal to fully guide an agent, especially given the presence of overlapping sibling tools.
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 100%, so baseline is 3. The description does not add any meaning beyond what the schema already provides for 'limit' and 'storyId'.
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?
Description clearly states verb 'get', resource 'comments', and context 'for a story'. It distinguishes from siblings like 'getComment' (single) and 'getCommentTree' (hierarchical).
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?
No guidance on when to use this tool over siblings such as 'getCommentTree' or 'getStoryWithComments'. No explicit context or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a comment tree for a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyId | Yes | The ID of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only states the tool's function without mentioning read-only nature, authentication needs, rate limits, or return structure. This is insufficient for informed invocation.
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?
The description is very concise, using a single sentence that directly states the purpose. It is efficiently front-loaded, but could be slightly more structured to include usage context without becoming verbose.
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?
Given the lack of annotations and output schema, the description fails to provide needed context about what a comment tree is, what the output contains, and when to prefer this tool over siblings. The tool is simple, but the description does not adequately compensate for missing structured data.
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?
The input schema has 100% coverage with a single parameter (storyId) described. The description does not add extra semantics beyond the schema. Per guidelines, baseline is 3 when schema coverage is high, and no additional value is provided.
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 description clearly identifies the action (Get) and resource (comment tree for a story). It hints at a hierarchical structure, but does not explicitly distinguish from siblings like getComments or getStoryWithComments, which could also retrieve comments. The specificity is good but not fully differentiated.
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?
The description provides no guidance on when to use this tool versus alternatives such as getComments, getStoryWithComments, or getComment. An agent would need to infer the appropriate scenario without any help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get multiple stories by type (top, new, best, ask, show, job)
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | The type of stories to fetch | |
| limit | No | The maximum number of stories to fetch |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey all behavioral traits. It states 'get multiple stories' but does not disclose ordering, pagination, rate limits, or the format of returned data (e.g., story IDs vs full objects). The limit parameter is described in the schema, but behavioral details are lacking.
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?
The description is a single sentence of 9 words, efficiently conveying the tool's purpose. No extraneous information is included.
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?
For a simple retrieval tool with two parameters and no output schema, the description is moderately complete. It covers the core functionality, but omits details about the output format (list of story objects or IDs) and potential behavior with invalid types or limits. Slightly more context would improve completeness.
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 description coverage is 100%, so the schema already explains both parameters. The description adds no additional meaning beyond listing the enum values, which are also in the schema. The baseline score of 3 is appropriate.
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 description clearly states the tool retrieves multiple stories and specifies the exact story types (top, new, best, ask, show, job). It distinguishes from sibling tools like getStory (single story) and getComments, making the purpose unambiguous.
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?
The description indicates when to use the tool (by story type) but does not explicitly mention when not to use it or provide alternatives. However, the sibling tool names suggest getStory for a single story, so the usage context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single story by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It implies a simple read operation but does not disclose whether there are any side effects, error conditions, or details about the return value beyond retrieving a story.
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?
The description is a single, front-loaded sentence with no unnecessary words. It is concise and effectively communicates the core functionality.
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?
For a simple get-by-ID tool with no output schema, the description is largely adequate. However, it could be improved by contrasting with getStoryWithComments or mentioning default behavior (e.g., returns story details without comments).
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 100% (id parameter with description). The tool description adds no additional meaning beyond what the schema already provides ('The ID of the story'). Baseline 3 is appropriate.
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 description 'Get a single story by ID' clearly states the verb (get), resource (story), and identifier method (by ID), distinguishing it from siblings like getStories (plural) and getStoryWithComments.
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?
No guidance is provided on when to use this tool versus alternatives like getStories or getStoryWithComments. The description does not specify context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a story with its comments
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether comments are top-level only or include nested replies, if the tool is read-only, or any rate limits. The name implies a combined result but lacks specifics.
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?
The description is a single sentence with no wasted words, but it could be slightly expanded to include key behavior without becoming verbose.
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?
Given the complexity of retrieving a story with its comments (likely nested) and the absence of an output schema, the description is too brief. It does not explain the response format or pagination behavior, leaving the agent with insufficient information.
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?
The schema description for the only parameter 'id' is already provided ('The ID of the story'), and the tool description does not add any additional meaning beyond that.
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 description clearly states the tool retrieves a story along with its comments, which is a specific verb-resource pair. It distinguishes from siblings like getStory (story only) and getComments (comments only).
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?
No guidance is provided on when to use this tool instead of alternatives like getStory plus getComments, or how it handles nested comments. The agent has no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a user profile by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the user |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral details like error handling or rate limits. However, for a simple read operation, the minimal disclosure is acceptable.
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?
Single sentence, no wasted words. Front-loaded with the key action and resource.
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?
Given the simplicity (one required parameter, no output schema), the description is mostly adequate. It could mention what a user profile contains, but not essential.
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 100% and the parameter 'id' is described in the schema as 'The ID of the user'. The description merely echoes this, adding no additional meaning beyond the schema.
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 description clearly states the verb 'Get' and the resource 'user profile', with the parameter 'by ID'. It distinguishes from sibling tools like getComment and getStory.
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?
No guidance on when to use this tool versus alternatives such as getUserSubmissions or search. The description only states what it does, not the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a user's submissions
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the user |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states 'Get a user's submissions' without revealing whether the operation is read-only, what side effects occur, any rate limits, or what happens with invalid IDs.
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?
The description is very short with one sentence. While it is concise, it lacks substance and fails to provide value beyond a basic label. It could be improved by adding more detail without becoming verbose.
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?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is incomplete. It does not explain what constitutes a 'submission', the expected output format, pagination, or error handling, leaving the agent to guess.
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?
The input schema has 100% coverage for the only parameter 'id', which already has a description. The tool description adds no additional meaning or context beyond the schema, so a baseline score of 3 is appropriate.
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 description 'Get a user's submissions' uses a specific verb ('Get') and resource ('user's submissions'), clearly indicating what the tool does. However, it does not differentiate from siblings like getComments or getStories, which also retrieve user-related 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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or any justification for selecting this tool over sibling tools like getUser or search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for stories and comments on Hacker News
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | The page number | |
| type | No | The type of content to search for | all |
| query | Yes | The search query | |
| hitsPerPage | No | The number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It only states the tool searches, without mentioning pagination behavior, ordering, rate limits, or what happens with no results. This leaves key behavioral aspects unspecified.
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?
The description is a single concise sentence with no fluff. It efficiently conveys the core functionality without unnecessary words.
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?
Given the tool has 4 parameters and no output schema, the description is too minimal. It does not explain search mechanics (e.g., full-text search, ordering), result expectations, or how to effectively use parameters like type and pagination. It lacks completeness for a search tool of this complexity.
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 description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it merely restates the tool's purpose. Parameter details (page, type, hitsPerPage) are already adequately described in the schema.
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 description 'Search for stories and comments on Hacker News' clearly states the action (search) and target (stories and comments on Hacker News). It effectively distinguishes from sibling tools like getStories, findAskHN, etc., which are more specific retrieval operations.
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?
The description provides no guidance on when to use this tool versus alternatives like getStories, findAskHN, or extractStartupInsights. It lacks context about when a general search is appropriate versus more targeted queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a story and comment thread with deterministic heuristics
| Name | Required | Description | Default |
|---|---|---|---|
| storyId | Yes | The Hacker News story ID | |
| maxDepth | No | Maximum comment nesting depth to analyze | |
| maxComments | No | Maximum number of comments to analyze |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'deterministic heuristics' but does not disclose whether the tool is read-only, requires authentication, or has rate limits. No side effects or behavioral traits beyond the vague heuristic term.
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?
Single sentence, no wasted words. Extremely concise while conveying the core purpose.
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?
Given the complexity of summarization and lack of output schema, the description is incomplete. It does not explain what the summary looks like, what 'deterministic heuristics' entails, or how the output differs from raw data from sibling tools.
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 100%, so baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions for storyId, maxDepth, and maxComments.
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 description clearly states the tool summarizes a story and comment thread using deterministic heuristics. It differentiates from sibling tools like getStoryWithComments (raw data) and search. However, it does not specify the type of summary (e.g., key points, sentiment).
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?
No guidance on when to use this tool over alternatives like getStoryWithComments, getCommentTree, or search. The description does not mention context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.2compareLaunchesextractStartupInsightsfindAskHNfindShowHNgetCommentgetCommentsgetCommentTreegetStoriesgetStorygetStoryWithCommentsgetUsergetUserSubmissionssearchsummarizeThreadScored across 14 tools
Most tools have clearly distinct purposes, but 'getStoryWithComments' overlaps with 'getStory' plus 'getComments', and 'search' could be used instead of 'findAskHN' or 'findShowHN'. These overlaps are minor and acceptable.
All tools use consistent camelCase naming with a verb_noun pattern (e.g., 'getComment', 'findShowHN', 'search'). No mixed conventions.
14 tools is well-scoped for a Hacker News reader, covering stories, comments, users, search, and specialized insights without being overwhelming or too thin.
Covers all major read operations (stories, comments, users, search) and adds valuable specialized tools like 'compareLaunches'. Missing write operations (post, vote) which are appropriate for a read-oriented API.
HN front-page, Algolia full-text search, and Show HN launch tracker.
Browse Hacker News feeds, threads, and user profiles with full-text search.
Deterministic Hacker News developer sentiment, themes & feature requests via MCP. No API key.
Search startups and founders, match companies to products, and manage outreach lists.