HN Pulse is an MCP server that provides AI assistants with read access to Hacker News data through 8 specialized tools. No API keys required — it uses the public HN Firebase and Algolia APIs.
Get Top Stories: Fetch current top-ranked HN stories by score and recency (up to 30)
Get New Stories: Retrieve the most recently submitted stories (up to 30)
Get Story Details: Access full story info including title, URL, score, and a comment tree with configurable depth
Search Stories: Full-text search across HN stories and comments via Algolia, with tag filtering (story, comment, ask_hn, show_hn, job), sorting by relevance or date, and pagination
Get User Profile: View a user's karma, about text, account creation date, and optionally their recent submissions
Get Job Listings: Access current job postings from YC companies and the community (up to 20)
Get Ask HN: Fetch recent community questions (up to 20)
Get Show HN: Retrieve recent project and tool showcases (up to 20)
Additionally, when enabled, it can fetch the full text content of external article URLs linked from HN stories. It supports both stdio and HTTP transports and works with Claude Desktop, Cursor, VS Code, and other MCP-compatible AI assistants.
Click on "Install 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., "@HN Pulse Search for recent discussions about AI agents and summarize the consensus."
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 Hacker News MCP Server built with arcade-mcp, plus a Claude-powered research agent that uses it.
HN Pulse gives any MCP-compatible AI assistant (Claude Desktop, Cursor, VS Code) direct read access to Hacker News — top stories, search, comments, user profiles, job listings, Ask HN, and Show HN — all via the public HN Firebase and Algolia APIs. No API keys required for the server.
HN Pulse MCP Server — 8 tools:
Tool | Description |
| Top N HN stories by ranking |
| Most recently submitted stories |
| Full story with filtered comment tree |
| Algolia full-text search across HN |
| Karma, about text, and account age |
| Current HN job postings |
| Recent Ask HN posts |
| Recent Show HN posts |
HN Fetch MCP Server — 1 supplementary tool (second service):
Tool | Description |
| Fetches the full text of any article URL |
The included research agent wraps these tools with Claude to answer natural-language queries like:
"What's the HN community saying about Rust in 2025?"
"Find recent AI startup job listings"
"Summarise the top Show HN projects this week"
"What is user pg's about section?"
Related MCP server: HackerNews MCP Server
User → agent/agent.py ──stdio──► src/hn_pulse/server.py
│
┌─────────────┼─────────────────┐
▼ ▼ ▼
HN Firebase API Algolia HN Search (no auth needed)
hacker-news.firebaseio.com hn.algolia.com/api/v1The agent spawns the MCP server as a subprocess, connects via stdio transport, then uses LangGraph's create_react_agent with langchain-mcp-adapters to bridge MCP tools into a standard ReAct loop: Claude chooses a tool → agent calls it via MCP → result fed back to Claude → loop until done.
Conversation state is persisted across turns in interactive mode via LangGraph's MemorySaver checkpointer — the agent remembers what it said earlier in the same session. Each session gets a UUID thread_id. One-shot mode always starts a fresh thread.
Multi-service: when ENABLE_FETCH=1 is set, the agent also connects to the HN Fetch MCP server, allowing Claude to read full article content from any HN story URL.
Python 3.10+
uv — brew install uv
Anthropic API key — only for the research agent
git clone https://github.com/<your-username>/hn-pulse.git
cd hn-pulse
# Create virtual environment and install all dependencies
uv venv
uv pip install -e ".[agent,dev]"
# Copy env template
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY (only needed for the agent)uv run src/hn_pulse/server.py stdio
# or simply:
uv run src/hn_pulse/server.pyuv run src/hn_pulse/server.py http
# API docs available at http://127.0.0.1:8000/docs# Install arcade CLI if you haven't already
uv tool install arcade-mcp
# Auto-configure Claude Desktop to use this server
arcade configure claude# Interactive mode — stateful (agent remembers the conversation)
python agent/agent.py
# One-shot mode
python agent/agent.py "What are people saying about Rust in 2025?"
# One-shot with structured output (pipeline-composable)
python agent/agent.py "Summarise top AI stories" --output report.md
python agent/agent.py "What's trending?" --json
# Enable multi-service: also connect the URL fetch server
ENABLE_FETCH=1 python agent/agent.py "What does the top HN story say?"The agent spawns the MCP server(s) automatically as subprocesses via stdio.
Start the server on the remote machine, binding to all network interfaces:
# On the remote machine (replace 8000 with your preferred port)
uv run src/hn_pulse/server.py http --host 0.0.0.0 --port 8000Then point the agent at it using MCP_SERVER_URL:
# On the client machine
export MCP_SERVER_URL=http://<remote-ip>:8000/mcp/
python agent/agent.py "What's trending on HN today?"The agent automatically switches from stdio to HTTP transport when MCP_SERVER_URL is set — no code changes needed. The MCP endpoint is always at /mcp/.
# Build and start both MCP servers as containers
docker compose up --build
# Run the agent against the deployed services
MCP_SERVER_URL=http://localhost:8000/mcp/ \
HN_FETCH_URL=http://localhost:8001/mcp/ \
ANTHROPIC_API_KEY=sk-... \
python agent/agent.py "Summarise the top story and read its full article"docker-compose.yml starts two services: hn-server (port 8000) and fetch-server (port 8001), each with health checks. Both are built from the same Dockerfile.
If you are using Claude Code, two slash commands are available after cloning:
Skill | What it does |
| Validates prerequisites and runs the research agent in one-shot mode |
| Runs the full test suite or a specific tier |
Examples:
/hn-research What are people saying about Rust in 2025?
/run-evals
/run-evals unit
/run-evals evalBoth skills check for ANTHROPIC_API_KEY and print clear fix instructions if it is missing. Skills are defined in .claude/commands/.
# Unit tests — zero API cost, mocked HTTP
pytest tests/unit/ -v
# Integration tests — starts the real server, zero API cost
pytest tests/integration/ -m integration -v
# Eval tests — requires ANTHROPIC_API_KEY, ~$0.002 total (uses claude-haiku)
pytest tests/evals/ -m eval -v
# All tests except evals
pytest -m "not eval" -vOr use the Makefile shortcuts:
make install # install all deps
make test # unit + integration (no API key needed)
make test-eval # eval tier only (requires ANTHROPIC_API_KEY)
make lint # ruff check
make typecheck # mypy
make check # lint + typecheck + test (full local CI)Suite | Count | What it validates |
Unit | 51 tests | Each tool function in isolation — happy path + error scenarios (mocked HTTP via pytest-httpx) |
Integration | 3 tests | MCP server starts, all 8 tools registered with valid schemas |
Evals | 10 parametrized cases | Claude selects the correct tool for 10 natural-language queries |
hn-pulse/
├── .claude/
│ └── commands/
│ ├── hn-research.md # /hn-research — runs the research agent
│ └── run-evals.md # /run-evals — three-tier test runner
├── .github/
│ └── workflows/
│ └── ci.yml # CI: lint + typecheck + tests on PR; evals on main
├── src/
│ ├── hn_pulse/
│ │ ├── server.py # MCPApp entrypoint — registers all 8 tools
│ │ ├── client.py # httpx client factory (HN + Algolia)
│ │ ├── types.py # TypedDict definitions (Story, SearchResponse, …)
│ │ └── tools/
│ │ ├── common.py # Shared fetch_item, gather_items, constants
│ │ ├── stories.py # get_top_stories, get_new_stories
│ │ ├── item.py # get_story_details
│ │ ├── search.py # search_stories (Algolia)
│ │ ├── users.py # get_user_profile
│ │ └── specials.py # get_job_listings, get_ask_hn, get_show_hn
│ └── hn_extras/
│ ├── fetch.py # fetch_article tool (HTML → plain text)
│ └── server.py # Second MCPApp — URL article fetcher
├── agent/
│ └── agent.py # Stateful LangGraph agent — multi-service, --output/--json
├── tests/
│ ├── unit/ # pytest-httpx mocked tests (51 total, incl. error scenarios)
│ ├── integration/ # real MCP server startup tests
│ └── evals/ # Claude tool-selection accuracy tests
├── docs/
│ ├── spec.md # Spec-driven development prompt to recreate this project
│ └── systems-design.html # Architecture diagram + design trade-offs
├── Dockerfile # Single image for both MCP servers
├── docker-compose.yml # hn-server (8000) + fetch-server (8001)
├── Makefile # make check, make test, make lint, make typecheck
├── .pre-commit-config.yaml
├── pyproject.toml
└── .env.exampleTools as plain async functions: Each tool is a regular Python async def — no framework decorators. They're registered with app.add_tool() in server.py. This makes unit testing trivial: call await get_top_stories(count=5) directly without an MCP server.
Concurrent item fetches: The HN Firebase API returns only ID arrays from feed endpoints. Fetching N stories naively would require N sequential round trips. All tools use asyncio.gather() to fetch items in parallel, reducing latency to ~2 round trips regardless of count.
Algolia metadata stripping: Algolia search results include _highlightResult, children (arrays of comment IDs), and other metadata that bloat LLM context. _clean_hit() strips these before returning, reducing each result from ~2 KB to ~200 bytes.
Shared helpers (tools/common.py): fetch_item and gather_items are the single canonical implementations used by all feed tools — no duplicate private helpers. Constants (MAX_STORY_COUNT, etc.) live here so magic numbers never appear in tool files.
LangGraph agent: agent/agent.py uses create_react_agent from LangGraph with MultiServerMCPClient from langchain-mcp-adapters — the same pattern used by ArcadeAI reference projects. MemorySaver + thread_id gives the interactive agent persistent conversation memory across turns.
Multi-service orchestration: MultiServerMCPClient connects to both hn_pulse and hn_fetch simultaneously. The agent can search HN for a story and then fetch the full article in a single reasoning loop — each service independently local or remote.
Structured deliverables: --output report.md writes a formatted Markdown report; --json prints a structured payload (query, answer, tools_used, timestamp) for downstream pipeline consumption.
Containerised: Dockerfile + docker-compose.yml deploy both MCP servers as isolated containers with health checks. docker compose up --build replaces the entire manual venv/install flow.
For the full spec used to build this project (suitable for reproducing it with an AI coding agent), see docs/spec.md.
Hacker News API — Firebase REST API (public, no auth)
Algolia HN Search API — Full-text search (public, no auth)
arcade-mcp — MCP server framework
Anthropic Python SDK — Claude API client
mcp Python SDK — MCP protocol client
MIT
Fetch recent Ask HN posts — questions posed to the Hacker News community.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of Ask HN posts to return (1-20) |
| Name | Required | Description |
|---|---|---|
| result | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With minimal annotations provided (only title), the description carries the full burden of behavioral disclosure. It mentions 'recent' implying a temporal filter but fails to specify the time window, rate limits, authentication requirements, default behavior when the optional 'count' parameter is omitted, or confirmation that this is a read-only operation.
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 the action verb. The em-dash efficiently clarifies the domain without redundancy. Every word earns its place with zero waste.
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 presence of an output schema (documenting return values) and 100% input schema coverage, the description provides sufficient context for this simple retrieval tool. It adequately identifies the resource scope, though it could benefit from clarifying the optional nature of the parameter.
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%, documenting the 'count' parameter with its valid range (1-20). The description adds no parameter-specific context, but with complete schema coverage, 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 uses specific verb 'Fetch' with clear resource 'Ask HN posts' and clarifies the domain with 'questions posed to the Hacker News community.' This effectively distinguishes the tool from siblings like GetShowHn, GetJobListings, and GetTopStories by explicitly naming the post type and explaining what 'Ask HN' means.
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 states what the tool does but provides no guidance on when to use it versus alternatives like GetNewStories or SearchStories. It does not indicate prerequisites, filtering limitations, or recommend this tool over other HN content retrieval options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch current job postings from Hacker News (YC companies and community job posts).
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of job listings to return (1-20) |
| Name | Required | Description |
|---|---|---|
| result | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only a title annotation provided, the description carries full behavioral burden. It adds valuable content context ('YC companies and community job posts') indicating data characteristics, but omits operational details like rate limits, caching behavior, or authentication requirements.
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 efficient sentence with no waste. Front-loaded with action verb and clear scope. The parenthetical detail earns its place by clarifying content source without verbosity.
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?
Appropriate for a simple read-only tool with one optional parameter and an existing output schema. Description adequately covers intent and data domain without needing to explain return values or complex nested structures.
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% for the single 'count' parameter which is fully documented in the schema. Description provides no additional parameter semantics, warranting the baseline score of 3 for high-coverage scenarios.
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?
Employs specific verb 'Fetch' with clear resource 'job postings' from 'Hacker News'. Parenthetical '(YC companies and community job posts)' clarifies data scope and effectively distinguishes this from story-focused siblings like GetTopStories or GetAskHn.
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 resource type (jobs vs stories/users) provides implied usage context that distinguishes it from siblings, but lacks explicit when-to-use guidance or comparisons to alternatives like SearchStories that might also return job-related content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the most recently submitted stories from Hacker News.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of new stories to return (1-30) |
| Name | Required | Description |
|---|---|---|
| result | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral annotations are provided (empty annotations object), so the description carries the full disclosure burden. The verb 'Fetch' implies a read-only operation, but the description does not confirm idempotency, mention rate limiting, authentication requirements, or caching behavior. It does not contradict any annotations, but adds minimal behavioral context beyond the operation name.
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 that communicates the core function without redundant phrases or repetition of the tool name. Every word serves the purpose of defining the scope (recently submitted stories) and resource (Hacker News).
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 low complexity (1 optional parameter, 100% schema coverage, output schema present), the description is minimally sufficient. It does not need to explain return values due to the output schema. However, with seven sibling tools available, the description could be more complete by clarifying the 'newness' concept versus other listings.
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?
Input schema has 100% description coverage for its single parameter (count). The description does not mention the parameter or provide usage examples, but given the high schema coverage, the baseline score of 3 is appropriate—the schema sufficiently documents the parameter semantics without requiring redundant description text.
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 fetches (reads) the most recently submitted stories from Hacker News. The phrase 'most recently submitted' effectively distinguishes this from the sibling GetTopStories (which retrieves top-ranked stories) and from filtered endpoints like GetAskHn or GetJobListings. However, it does not explicitly differentiate from SearchStories or provide explicit comparative guidance.
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 its siblings (e.g., when to choose new stories over top stories, or when to use SearchStories instead). There are no stated prerequisites, exclusions, or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch recent Show HN posts — projects and tools shared by the HN community.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of Show HN posts to return (1-20) |
| Name | Required | Description |
|---|---|---|
| result | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only title, so description carries full disclosure burden. It adds valuable semantic context that Show HN contains projects/tools, but omits operational details: no mention of what 'recent' means (time window), rate limits, caching behavior, or pagination. No contradiction with annotations.
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 with zero waste. Front-loaded with action ('Fetch recent Show HN posts') followed by clarifying em-dash explaining domain semantics. Every word earns its place.
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?
Appropriate for tool complexity: output schema exists (covering return values), only 1 parameter with 100% schema coverage, and content type is clearly identified. Minor gap: 'HN' abbreviation assumes familiarity with Hacker News; explicit mention of 'Hacker News' would improve completeness for agents without that context.
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% (count parameter fully documented with range 1-20). Description does not reference the count parameter or add syntax/format examples, so baseline 3 applies per rubric guidelines for high-coverage schemas.
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?
Excellent specificity: uses concrete verb 'Fetch' with resource 'Show HN posts' and distinguishes from siblings (Ask HN, Job Listings, Top Stories) by defining the content type as 'projects and tools shared by the HN community.' The em-dash construction efficiently differentiates this curated category from other HN content types.
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?
Provides implied usage through domain terminology ('Show HN' = projects/tools), helping distinguish from Ask HN (questions) or Job Listings. However, lacks explicit when-to-use guidance or named alternatives (e.g., 'use GetNewStories for chronological content').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a Hacker News story including title, URL, score, and top comments.
| Name | Required | Description | Default |
|---|---|---|---|
| story_id | Yes | The numeric Hacker News story ID | |
| max_comments | No | Maximum top-level comments to include (1-20) | |
| include_replies | No | Whether to include replies under each top comment |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With minimal annotations (only title), description carries burden of behavioral disclosure. It reveals the hierarchical comment structure (top comments vs replies) which hints at the nested data returned, but omits safety hints (read-only), error behavior (404 for invalid ID), or rate limiting.
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 efficient sentence (12 words), front-loaded with verb. No redundancy or filler. Every clause earns its place by conveying scope (full details) and key data categories.
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?
Appropriate for a fetch-by-ID tool with output schema present. Covers primary return fields. Minor gap: doesn't hint at error cases (story not found, private/deleted stories) or authentication requirements implied by the API.
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. Description mentions 'top comments' which reinforces the max_comments parameter semantics, but adds no syntax guidance (e.g., integer format) or clarifications beyond what schema already provides.
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?
Clear verb (Get) and resource (Hacker News story), with specific fields enumerated (title, URL, score, comments). Uses singular 'story' implying lookup by ID vs siblings that return lists, though explicit differentiation from list-fetching siblings (GetTopStories, GetNewStories) is absent.
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 provided on when to use this vs sibling tools. Missing crucial workflow context: that this requires a story_id likely obtained from GetTopStories/GetNewStories/HnPulse_SearchStories, and no mention of required parameter constraints beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current top stories from Hacker News, ranked by score and recency.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of top stories to return (1-30) |
| Name | Required | Description |
|---|---|---|
| result | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only redundant title with no safety hints, so description carries the burden. It discloses the ranking algorithm (score and recency) but omits read-only safety, rate limits, or cache behavior. 'Fetch' implies a safe read operation, but explicit confirmation would improve this.
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 of 12 words. Every element earns its place: action (Fetch), subject (current top stories), source (Hacker News), and behavior (ranked by score and recency). No redundancy or waste.
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?
Adequate for a simple read operation with one optional parameter and an existing output schema. Captures the essential differentiator (ranking algorithm). Could be enhanced by noting this retrieves front-page/voted content specifically, but covers the necessary context.
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% ('Number of top stories to return (1-30)'), fully documenting the optional count parameter. Description adds no parameter-specific semantics beyond the schema, which is appropriate given the high coverage baseline.
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?
States specific verb (Fetch), resource (stories from Hacker News), and scope (ranked by score and recency). The ranking criteria implicitly distinguish it from siblings like GetNewStories (chronological) and GetAskHn (category-specific), though it doesn't explicitly name alternatives.
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?
Provides implied guidance through the ranking criteria ('score and recency' vs 'new'), but lacks explicit instructions on when to choose this over GetNewStories, GetAskHn, or SearchStories. No prerequisites or error conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Hacker News user's profile: karma, about text, and account creation date.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Hacker News username (case-sensitive) | |
| include_recent_submissions | No | Whether to include the last 10 submission IDs |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title with no behavioral hints. The description adds valuable context by listing the specific data fields returned (karma, about text, creation date), but omits other behavioral traits like error handling for non-existent users, rate limits, or caching 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 sentence with no waste. Front-loaded with action verb and resource, followed by colon-delimited enumeration of return fields. Every word earns its place.
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 presence of an output schema and simple 2-parameter input, the description is appropriately complete. It identifies the key return fields, which helps agent selection, though it could mention the optional submissions parameter behavior.
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?
With 100% schema description coverage, the schema fully documents both parameters (username case-sensitivity and include_recent_submissions). The description focuses on return fields rather than parameter semantics, maintaining the baseline score appropriate for high-coverage schemas.
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 provides a specific verb ('Get'), resource ('Hacker News user's profile'), and distinguishes from siblings by targeting user data rather than stories. It enumerates the specific fields returned (karma, about text, creation date), making the scope crystal clear.
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?
While the description clearly targets user profiles (implied distinction from story-focused siblings like GetTopStories), it lacks explicit guidance on when to use this vs. alternatives. No 'when-not' or prerequisite conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Hacker News stories and comments using Algolia full-text search.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query string | |
| sort_by | No | Sort results by relevance (default) or recency | |
| tags | No | Filter by HN tag: story, comment, ask_hn, show_hn, or job (default: story) | |
| num_results | No | Number of results to return (1-20) | |
| page | No | Page number for pagination (0-indexed) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only title, so description carries full burden. It successfully discloses the external Algolia dependency and scope (stories AND comments), but omits safety profile (read-only vs destructive), rate limits, or pagination behavior details.
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 the action verb. Every word earns its place—'Algolia' signals external service, 'full-text' clarifies search type, and 'stories and comments' defines scope with zero redundancy.
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?
Adequate given the presence of an output schema and complete input schema documentation. However, with minimal annotations (no hints), the description should ideally disclose auth requirements or rate limits for the Algolia integration to be 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 description coverage is 100%, establishing baseline 3. Description adds context that this is 'full-text search' (clarifying query behavior) and mentions 'comments' (relating to tags parameter), but does not elaborate on specific parameter syntax beyond 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?
Description provides specific verb ('Search'), clear resource ('Hacker News stories and comments'), and distinguishes from siblings by specifying 'Algolia full-text search'—indicating this is a query-based tool versus the 'Get' siblings that fetch specific feeds.
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 versus the sibling fetch tools (e.g., GetTopStories, GetNewStories). The 'Search' naming provides implicit contrast to 'Get', but no explicit 'when to use' or 'alternatives' guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose targeting specific Hacker News content types or functions. There is no overlap between fetching different story categories (Ask HN, Show HN, new, top), job listings, story details, user profiles, and search, making tool selection unambiguous.
All tools follow a perfectly consistent naming pattern: 'HnPulse_Get' + [specific resource/action]. This uniform verb_noun structure (with 'Get' as the verb) makes the tool set predictable and easy to understand at a glance.
With 8 tools, this server is well-scoped for its purpose of accessing Hacker News data. It covers the main content categories and essential functions without being overwhelming or sparse, providing a balanced and focused tool surface.
The tool set comprehensively covers reading and searching Hacker News content, including stories, comments, jobs, and user profiles. A minor gap is the lack of write operations (e.g., posting or voting), but these are likely outside the server's intended scope, and the read/search coverage is complete for typical agent workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Browse Hacker News feeds, threads, and user profiles with full-text search.
HN front-page, Algolia full-text search, and Show HN launch tracker.
Hacker News MCP — search and retrieve stories from Hacker News
Live Hacker News front page: top tech stories, points, comments, links. $0.01/query.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AnkamAndy/hn-pulse'
If you have feedback or need assistance with the MCP directory API, please join our Discord server