hn-mcp-server

Previous value: -"IDs on this page whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded."New value: +"IDs on this page whose fetch failed after retries or ran past the call's 50-second time budget. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded."

Previous value: -"Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged — noting when count was served at its per-call cap. Absent on the last page of a non-empty result with no failed IDs."New value: +"Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them (naming the call's 50-second time budget when it cut them), or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged — noting when count was served at its per-call cap. Absent on the last page of a non-empty result with no failed IDs."

Previous value: -"Maximum comments in one response, across all depth levels, at most 200 per call. A larger value is served at 200, and nextCursor continues from there. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops at a fixed 64,000-byte text budget. When either limit stops the traversal, nextCursor continues it."New value: +"Maximum comments in one response, across all depth levels, at most 200 per call. A larger value is served at 200, and nextCursor continues from there. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops between comments to stay within a fixed 64,000-byte budget on each surface — all content[] text, nextCursor and the rest of the trailer included, and the structuredContent JSON — though its first comment is always returned whole. When either limit stops the traversal, nextCursor continues it."

Previous value: -"Comment and poll-option IDs whose fetch failed after retries, so neither they nor their replies are in this response. They are not deleted or missing and may load on a later call. Failed comments ride in nextCursor and are retried when you continue; without one, call again, or pass an ID as itemId to fetch that comment and its replies. Absent when everything the traversal reached loaded."New value: +"Comment and poll-option IDs whose fetch failed after retries or ran past the call's 50-second time budget, so neither they nor their replies are in this response. They are not deleted or missing and may load on a later call. Failed comments ride in nextCursor and are retried when you continue; without one, call again, or pass an ID as itemId to fetch that comment and its replies. Absent when everything the traversal reached loaded."

Previous value: -"Pass as cursor, with the same itemId, to continue from the next unseen comment. Present when truncationReason is count, size, or rate_limited; absent on the last page."New value: +"Pass as cursor, with the same itemId, to continue from the next unseen comment. Present when truncationReason is count, size, rate_limited, or time; absent on the last page."

Previous value: -"Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, or rate-limit stop, or a larger depth or a comment id as itemId for a depth cut — noting when the maxComments or depth that stopped it was served at its per-call cap. Dead or deleted comments whose replies the depth limit cut are named by id, to pass as itemId, on the page that reaches them, since comments omits them. Absent when nothing was dropped, failed, or left unread."New value: +"Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, rate-limit, or time-budget stop, or a larger depth or a comment id as itemId for a depth cut — noting when the maxComments or depth that stopped it was served at its per-call cap. Dead or deleted comments whose replies the depth limit cut are named by id, to pass as itemId, on the page that reaches them, since comments omits them. Absent when nothing was dropped, failed, or left unread."

Previous value: -"True when comments remain unread: reachable through nextCursor (truncationReason count, size, or rate_limited), or below the depth limit (depth). Absent on a terminal page — including a thread that loads in full at exactly maxComments."New value: +"True when comments remain unread: reachable through nextCursor (truncationReason count, size, rate_limited, or time), or below the depth limit (depth). Absent on a terminal page — including a thread that loads in full at exactly maxComments."

Previous value: -"Why the traversal stopped short: count = maxComments (or the 1,000-item ceiling per call) was reached; size = the 64,000-byte response budget was reached; rate_limited = the HN API throttled the fetches; depth = replies lie below the depth limit, which nextCursor does not reach — raise depth or pass a comment id as itemId. When a cursor reason and a depth cut both apply, the cursor reason is reported."New value: +"Why the traversal stopped short: count = maxComments (or the 1,000-item ceiling per call) was reached; size = the page stopped between comments to keep content[] and structuredContent each within the 64,000-byte response budget; rate_limited = the HN API throttled the fetches; time = the call's 50-second time budget ran short because the HN API answered slowly or not at all; depth = replies lie below the depth limit, which nextCursor does not reach — raise depth or pass a comment id as itemId. When a cursor reason and a depth cut both apply, the cursor reason is reported."

Previous value: -[
-  "count",
-  "size",
-  "depth",
-  "rate_limited"
-]New value: +[
+  "count",
+  "size",
+  "depth",
+  "rate_limited",
+  "time"
+]

Previous value: -"Submission IDs in this window whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry with the same submissionOffset, or pass an ID to hn_get_thread to fetch that item alone. Absent when every submission in the window loaded."New value: +"Submission IDs in this window whose fetch failed after retries or ran past the call's 50-second time budget. They are not deleted or missing and may load on a later call: retry with the same submissionOffset, or pass an ID to hn_get_thread to fetch that item alone. Absent when every submission in the window loaded."

Previous value: -"Pagination context — which window of the history this page covers and the submissionOffset to send next, the submission IDs that failed to load and how to retry them, or a warning that the offset is past the end — noting when submissionCount was served at its per-call cap. Absent when the page reaches the end of the history with no failed IDs, or when no submissions were resolved."New value: +"Pagination context — which window of the history this page covers and the submissionOffset to send next, the submission IDs that failed to load and how to retry them, or a warning that the offset is past the end — noting when submissionCount was served at its per-call cap or the call's 50-second time budget cut the failed fetches, and closing with the submissions whose text was cut to keep the page within the 64,000-byte response budget. Absent when the page reaches the end of the history with no failed IDs and no cut text, or when no submissions were resolved."

Previous value: -"Body text (HTML stripped)."New value: +"Body text (HTML stripped). Cut short when the page would otherwise exceed the 64,000-byte response budget, with textTruncated set."

Added value: +{
+  "description": "True when text is a prefix of the body, cut short to keep the page within the 64,000-byte response budget — hn_get_thread with this id returns it whole. Absent when text is whole.",
+  "type": "boolean"
+}

Previous value: -"Search terms. Supports simple keywords — Algolia handles stemming and relevance, and a hit must contain every term. Trimmed before searching; blank or whitespace-only input is rejected. To find discussions of a page, pass its URL alone: a query with no spaces that starts with http://, https://, or www. is searched without that prefix, so submissions under either scheme, with or without www., all match. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound."New value: +"Search terms. Supports simple keywords — Algolia handles stemming and relevance, and a hit must contain every term. Matching is typo-tolerant and the last term also matches as a prefix (zig matches Zigbee); wrap a term in double quotes to match it exactly (\"zig\"), or put - before one to exclude it (\"zig\" -devlog). Trimmed before searching; blank or whitespace-only input is rejected. To find discussions of a page, pass its URL alone: a query with no spaces that starts with http://, https://, or www. is searched without that prefix, so submissions under either scheme, with or without www., all match. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound."

Previous value: -"How much of each hit to return. \"full\" includes every field. \"compact\" omits the two body-text fields — `text` and `highlights.text` — which together can repeat a long comment twice per hit; everything else (id, title, url, domain, author, points, comment count, timestamp, parent story, title highlight, matchedWords) is unchanged. Use \"compact\" to scan many results, then pass a hit id to hn_get_thread to read the body you skipped."New value: +"How much of each hit to return. \"full\" includes every field, within a 64,000-byte budget on each response surface: a page over it drops highlights.text from every hit (highlightsTextOmitted), and if still over, cuts the longest text bodies to one shared length (textTruncated) — every hit stays on the page. \"compact\" omits the two body-text fields — `text` and `highlights.text` — which together can repeat a long comment twice per hit; everything else (id, title, url, domain, author, points, comment count, timestamp, parent story, title highlight, matchedWords) is unchanged. Use \"compact\" to scan many results, then pass a hit id to hn_get_thread to read the body you skipped."

Added value: +{
+  "description": "True when highlights.text was dropped from every hit to keep this view \"full\" page within the 64,000-byte response budget; highlights.title and matchedWords remain. Absent otherwise.",
+  "type": "boolean"
+}

Previous value: -"Body snippet (comment_text or story_text), HTML stripped, with matched terms wrapped in `<em>…</em>`. A literal `<em>` typed into the body is indistinguishable from a marker. Absent when the body did not match, and always absent under view \"compact\" — matchedWords still lists what matched."New value: +"The matched body in full, not a snippet (comment_text or story_text), HTML stripped, with matched terms wrapped in `<em>…</em>` — the same text as `text` plus its markers. A literal `<em>` typed into the body is indistinguishable from a marker. Absent when the body did not match, when highlightsTextOmitted is true, and always under view \"compact\" — matchedWords still lists what matched."

Previous value: -"Body text, HTML stripped: a comment's text, a text post's body, or a job's description. A job description is returned but not keyword-searched or highlighted. Absent when the hit has no body, and always absent under view \"compact\" — call hn_get_thread with this id to read it."New value: +"Body text, HTML stripped: a comment's text, a text post's body, or a job's description. A job description is returned but not keyword-searched or highlighted. Cut short when the page would otherwise exceed the 64,000-byte response budget, with textTruncated set. Absent when the hit has no body, and always absent under view \"compact\" — call hn_get_thread with this id to read it."

Added value: +{
+  "description": "True when text is a prefix of the body, cut short to keep the page within the 64,000-byte response budget — hn_get_thread with this id returns it whole. Absent when text is whole.",
+  "type": "boolean"
+}

Previous value: -"Agent guidance, one string. It opens with the page state: the next page to request while more pages remain, the 1,000-hit ceiling on the last page of a search that matches more, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Notes on the inputs follow it. Absent when none applies."New value: +"Agent guidance, one string. It opens with the page state: the next page to request while more pages remain, the 1,000-hit ceiling on the last page of a search that matches more, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Notes on the inputs follow it, then, on a view \"full\" page fitted to the 64,000-byte response budget, a sentence naming what was omitted and the ids of hits whose text was cut. Absent when none applies."

Previous value: -"Number of stories to return. Larger counts take longer."New value: +"Number of stories to return, at most 100 per call. A larger value is served at 100, and the notice names the offset for the next page. Larger counts take longer."

Previous value: -100New value: +1000

Previous value: -"The count cap that was applied."New value: +"The count value served: as passed, or 100 when count was above that cap."

Previous value: -"Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result with no failed IDs."New value: +"Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged — noting when count was served at its per-call cap. Absent on the last page of a non-empty result with no failed IDs."

Previous value: -"Total comment count. Absent for jobs."New value: +"HN's count of live comments in the thread (descendants); dead and deleted comments are not counted. Absent for jobs."

Previous value: -"How many levels of replies to resolve. 0 = just the item, no comments. 1 = direct replies only. Replies below this depth are never fetched — to read them, raise depth or call again with a specific comment's itemId to drill into its subtree. Ignored when cursor is set: the depth the cursor was issued with applies."New value: +"How many levels of replies to resolve, at most 10 per call. 0 = just the item, no comments. 1 = direct replies only. A larger value is served at 10. Replies below the depth served are never fetched — to read them, raise depth up to 10, or call again with a comment from the deepest level returned, or one notice names, as itemId to drill into its subtree. Ignored when cursor is set: the depth the cursor was issued with applies."

Previous value: -10New value: +100

Previous value: -"Maximum comments in one response, across all depth levels. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops at a fixed 64,000-byte text budget. When either limit stops the traversal, nextCursor continues it."New value: +"Maximum comments in one response, across all depth levels, at most 200 per call. A larger value is served at 200, and nextCursor continues from there. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops at a fixed 64,000-byte text budget. When either limit stops the traversal, nextCursor continues it."

Previous value: -200New value: +1000

Previous value: -"The maxComments cap that was applied."New value: +"The maxComments value served: as passed, or 200 when maxComments was above that cap."

Previous value: -"Present and `true` when the comment author matches the root item author (OP replying within their own thread). Omitted otherwise — including when either author is missing. Most threads carry no OP replies, so absence is the common case; treat missing as \"not OP\" rather than unknown."New value: +"Present and `true` when the comment author submitted the story or poll the thread belongs to (OP replying within their own thread) — for a comment root, the story at item.storyId. Omitted otherwise, including when either author is missing. Most threads carry no OP replies, so absence usually means \"not OP\"; it means unknown when the thread's root has no author (a deleted story, for example) or when notice says replies are not marked."

Previous value: -"Parent item ID."New value: +"Parent item ID: the root or another comment. It can name a dead or deleted comment, which this list omits while still returning its replies; pass that ID as itemId to see it marked."

Previous value: -"Machine-readable failure mode. Declared by this tool: `item_not_found`: HN reports no item exists for the given itemId. `invalid_cursor`: The cursor was issued for a different itemId than the one passed with it. `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `item_not_found`: HN reports no item exists for the given itemId. `invalid_cursor`: The cursor is not one this tool issued, was altered, or was issued for a different itemId than the one passed with it. `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."

Previous value: -"Total comment count."New value: +"HN's count of live comments in the thread; dead and deleted comments are not counted."

Added value: +{
+  "description": "For a comment root, the ID of the story or poll its discussion belongs to — pass it as itemId for the whole thread, or as storyId to hn_search_content. Absent for other roots, and when the story could not be found (notice says why).",
+  "type": "number"
+}

Previous value: -"Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, or rate-limit stop, or a larger depth or a comment id as itemId for a depth cut. Absent when nothing was dropped, failed, or left unread."New value: +"Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, or rate-limit stop, or a larger depth or a comment id as itemId for a depth cut — noting when the maxComments or depth that stopped it was served at its per-call cap. Dead or deleted comments whose replies the depth limit cut are named by id, to pass as itemId, on the page that reaches them, since comments omits them. Absent when nothing was dropped, failed, or left unread."

Previous value: -"HN's total comment count for the root (descendants), which also counts dead and deleted comments. Absent for comment and job roots."New value: +"HN's count of live comments in the thread (descendants); dead and deleted comments are not counted. Absent for comment and job roots."

Previous value: -"Page size — how many submissions to resolve per call. Only used when includeSubmissions is true."New value: +"Page size — how many submissions to resolve per call, at most 50 per call. A larger value is served at 50, and the notice names the submissionOffset for the next page. Only used when includeSubmissions is true."

Previous value: -50New value: +1000

Previous value: -"How many submissions to skip before resolving, counting back from the most recent. Use with submissionCount to page through a long history: request offset 0, then offset submissionCount, and so on. The enrichment block echoes submissionOffset and, when more remain, the offset to send next. Only used when includeSubmissions is true."New value: +"How many submissions to skip before resolving, counting back from the most recent. Use with submissionCount to page through a long history: request offset 0, then advance by the page size served, and so on. The enrichment block echoes submissionOffset and, when more remain, the offset to send next. Only used when includeSubmissions is true."

Previous value: -"The submissionCount cap that was applied."New value: +"The submissionCount value served: as passed, or 50 when submissionCount was above that cap."

Previous value: -"Pagination context — which window of the history this page covers and the submissionOffset to send next, the submission IDs that failed to load and how to retry them, or a warning that the offset is past the end. Absent when the page reaches the end of the history with no failed IDs, or when no submissions were resolved."New value: +"Pagination context — which window of the history this page covers and the submissionOffset to send next, the submission IDs that failed to load and how to retry them, or a warning that the offset is past the end — noting when submissionCount was served at its per-call cap. Absent when the page reaches the end of the history with no failed IDs, or when no submissions were resolved."

Previous value: -"Comment count (stories/polls)."New value: +"HN's count of live comments in the thread (descendants); dead and deleted comments are not counted. Present for stories and polls."

Previous value: -"Filter results to a specific author. Useful for finding a user's posts on a topic (hn_get_user only shows recent submissions). Trimmed before filtering; omit the field to search all authors rather than passing a blank string."New value: +"Filter results to a specific author — useful for finding a user's posts on a topic. Matches the HN username exactly and is case-sensitive, so a re-cased name finds nothing. Trimmed before filtering; omit the field to search all authors rather than passing a blank string."

Previous value: -"Number of results to return."New value: +"Number of results to return, at most 50 per call. A larger value is served at 50: the search runs at count 50 from the hit where the requested page starts, and the notice names the count and page to pass next. With page above 0, that hit (page × count) must begin a page of 50 hits."

Previous value: -50New value: +1000

Previous value: -"Page number for pagination (0-indexed)."New value: +"Page number for pagination (0-indexed), counted in pages of count results."

Previous value: -"Search terms. Supports simple keywords — Algolia handles stemming and relevance. Trimmed before searching; blank or whitespace-only input is rejected. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound."New value: +"Search terms. Supports simple keywords — Algolia handles stemming and relevance, and a hit must contain every term. Trimmed before searching; blank or whitespace-only input is rejected. To find discussions of a page, pass its URL alone: a query with no spaces that starts with http://, https://, or www. is searched without that prefix, so submissions under either scheme, with or without www., all match. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound."

Previous value: -"Restrict results to one discussion: the id of a story or poll root, combined with the other filters. Pair with tags \"comment\" to search within a thread. Take it from hits[].storyId or the root item of hn_get_thread — a comment id matches nothing."New value: +"Restrict results to one discussion: the id of a story or poll root, combined with the other filters. Pair with tags \"comment\" to search within a thread. Take it from hits[].storyId, from a poll hit's own id (poll hits carry no storyId), or from hn_get_thread — the root item's id, or its item.storyId when the root is a comment. A comment id matches nothing."

Previous value: -"Filter results by content type: \"story\", \"comment\", \"poll\", or \"job\", or the story subsets \"ask_hn\", \"show_hn\", and \"front_page\". Omit to search all types."New value: +"Filter results by content type: \"story\", \"comment\", \"poll\", or \"job\", or the story subsets \"ask_hn\", \"show_hn\", and \"front_page\". \"front_page\" is the HN front page right now (about 30 stories); no filter selects stories from past front pages. The nearest proxy is \"story\" with dateRange and minPoints — without a query, the default relevance sort ranks by points. Omit to search all types, which also returns poll options (type \"pollopt\"): records with only an id, author, vote count, and date — hn_get_thread reads an option's text and poll."

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "hits",
-      "totalHits",
-      "page",
-      "totalPages"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "hits",
+      "criteria",
+      "totalHits",
+      "page",
+      "totalPages"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Previous value: -"The count cap that was applied."New value: +"The count value served: as passed, or 50 when count was above that cap."

Added value: +{
+  "additionalProperties": false,
+  "description": "The criteria this search ran with: each filter that was set, as sent — author trimmed, dateRange bounds as the exclusive UTC instants applied — then sort, count, and view, defaults included. Unset filters are absent. The searched query is in query.",
+  "properties": {
+    "author": {
+      "description": "Author filter — the username matched, trimmed.",
+      "type": "string"
+    },
+    "count": {
+      "description": "Hits per page sent: count as passed, or 50 when count was above that cap.",
+      "type": "number"
+    },
+    "dateRange": {
+      "additionalProperties": false,
+      "description": "Creation-time window as applied, with only the bounds that were set.",
+      "properties": {
+        "end": {
+          "description": "Items match only when created strictly before this instant: the end bound in ISO 8601 UTC, rounded up to the whole second.",
+          "type": "string"
+        },
+        "start": {
+          "description": "Items match only when created strictly after this instant: the start bound in ISO 8601 UTC, rounded down to the whole second.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "minPoints": {
+      "description": "Minimum score.",
+      "type": "number"
+    },
+    "sort": {
+      "description": "Sort order used.",
+      "enum": [
+        "relevance",
+        "date"
+      ],
+      "type": "string"
+    },
+    "storyId": {
+      "description": "Discussion filter: a story or poll root id.",
+      "type": "number"
+    },
+    "tags": {
+      "description": "Content-type filter.",
+      "enum": [
+        "story",
+        "comment",
+        "poll",
+        "job",
+        "ask_hn",
+        "show_hn",
+        "front_page"
+      ],
+      "type": "string"
+    },
+    "view": {
+      "description": "Projection applied to each hit.",
+      "enum": [
+        "full",
+        "compact"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "sort",
+    "count",
+    "view"
+  ],
+  "type": "object"
+}

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_query_or_filter`: Neither a query nor any filter was supplied, so there is nothing to search by. `invalid_date_range`: dateRange was supplied with neither bound, or with start not before end. `min_points_unscored_type`: minPoints was combined with tags \"comment\" or \"job\", record types Algolia stores without points. `upstream_rejected`: Algolia answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: Algolia answered with HTTP 429. `upstream_unavailable`: Algolia answered with a 5xx status. `upstream_html`: Algolia served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: Algolia answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_query_or_filter`: Neither a query nor any filter was supplied, so there is nothing to search by. `invalid_date_range`: dateRange was supplied with neither bound, or with start not before end. `min_points_unscored_type`: minPoints was combined with tags \"comment\" or \"job\", record types Algolia stores without points. `count_page_unaligned`: count was above the per-call cap of 50 with a page whose first hit (page × count) begins no page of 50 hits, so the requested page cannot be served from its start at the cap. `upstream_rejected`: Algolia answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: Algolia answered with HTTP 429. `upstream_unavailable`: Algolia answered with a 5xx status. `upstream_html`: Algolia served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: Algolia answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "missing_query_or_filter",
-  "invalid_date_range",
-  "min_points_unscored_type",
-  "upstream_rejected",
-  "upstream_rate_limited",
-  "upstream_unavailable",
-  "upstream_html",
-  "upstream_malformed"
-]New value: +[
+  "missing_query_or_filter",
+  "invalid_date_range",
+  "min_points_unscored_type",
+  "count_page_unaligned",
+  "upstream_rejected",
+  "upstream_rate_limited",
+  "upstream_unavailable",
+  "upstream_html",
+  "upstream_malformed"
+]

Previous value: -"A single Algolia search hit (story, comment, poll, or job)."New value: +"A single Algolia search hit (story, comment, poll, poll option, or job)."

Previous value: -"Parent story ID for comment hits; equals `id` for story hits."New value: +"Parent story ID for comment hits; equals `id` for story hits. Absent for polls, poll options, and jobs — a poll's own `id` is its discussion root."

Previous value: -"Comment or story body text (HTML stripped). Absent when the hit has no body, and always absent under view \"compact\" — call hn_get_thread with this id to read it."New value: +"Body text, HTML stripped: a comment's text, a text post's body, or a job's description. A job description is returned but not keyword-searched or highlighted. Absent when the hit has no body, and always absent under view \"compact\" — call hn_get_thread with this id to read it."

Added value: +{
+  "description": "Item type: story (Ask HN, Show HN, and front-page stories included), comment, poll, pollopt (one option of a poll), or job. Absent when the search record names no type.",
+  "enum": [
+    "story",
+    "comment",
+    "poll",
+    "pollopt",
+    "job"
+  ],
+  "type": "string"
+}

Previous value: -"Agent guidance: the next page to request while more pages remain, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Absent on the last page of a non-empty result."New value: +"Agent guidance, one string. It opens with the page state: the next page to request while more pages remain, the 1,000-hit ceiling on the last page of a search that matches more, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Notes on the inputs follow it. Absent when none applies."

Previous value: -"Current page number (0-indexed)."New value: +"Current page number (0-indexed), in pages of criteria.count hits. When count was above the per-call cap, the page of 50 where the requested page starts."

Previous value: -"The query that was searched. Absent for a filter-only search."New value: +"The query that was searched — for a URL query, without its leading scheme and www. Absent for a filter-only search."

Added value: +{
+  "description": "How many of totalHits paging can reach: Algolia serves at most 1,000 hits per search. Present only when totalHits exceeds that; split the search into narrower dateRange windows to reach the rest.",
+  "type": "number"
+}

Previous value: -"Total matching results across all pages."New value: +"Matching results across all pages, as Algolia counts them. An estimate when totalHitsExact is false — broad searches can be off by orders of magnitude — and paging reaches only the first 1,000 (see reachableHits)."

Added value: +{
+  "description": "True when totalHits is an exact count, false when it is an estimate, as it is for keyword searches and broad filter-only searches. Absent when Algolia does not say, and on a page past the 1,000-hit ceiling, where totalHits reads 0.",
+  "type": "boolean"
+}

Previous value: -"Number of pages Algolia will actually serve for this query. Not derived from totalHits — broad queries report a totalHits far larger than the reachable page range, so paginate against this value."New value: +"Number of pages of criteria.count hits Algolia will actually serve for this query, covering at most the first 1,000 hits. Not derived from totalHits — broad queries report a totalHits far larger than the reachable page range, so paginate against this value."

Previous value: -"Body snippet (comment_text or story_text) with matched terms wrapped in `<em>…</em>`. Absent when the body did not match, and always absent under view \"compact\" — matchedWords still lists what matched."New value: +"Body snippet (comment_text or story_text), HTML stripped, with matched terms wrapped in `<em>…</em>`. A literal `<em>` typed into the body is indistinguishable from a marker. Absent when the body did not match, and always absent under view \"compact\" — matchedWords still lists what matched."

Previous value: -"Title snippet with matched terms wrapped in `<em>…</em>`. Absent when the title did not match."New value: +"Title snippet with matched terms wrapped in `<em>…</em>`. Titles are not HTML, though some arrive entity-encoded; entities are decoded and no tags are stripped, so a literal `<em>` in the title is indistinguishable from a marker. Absent when the title did not match."

Added value: +{
+  "description": "IDs on this page whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

Previous value: -"Agent guidance: the offset to pass for the next page while more stories remain, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result."New value: +"Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result with no failed IDs."

Added value: +{
+  "description": "nextCursor from a previous call, passed with the same itemId, to continue the traversal at the next unseen comment without repeating or skipping any. Omit to start from the top.",
+  "type": "string"
+}

Previous value: -"How many levels of replies to resolve. 0 = just the item, no comments. 1 = direct replies only. Popular stories often have more top-level comments than maxComments — to see nesting, raise maxComments together with depth, or call again with a specific comment's itemId to drill into a subtree."New value: +"How many levels of replies to resolve. 0 = just the item, no comments. 1 = direct replies only. Replies below this depth are never fetched — to read them, raise depth or call again with a specific comment's itemId to drill into its subtree. Ignored when cursor is set: the depth the cursor was issued with applies."

Previous value: -"ID of the story, comment, or poll to fetch the thread for."New value: +"ID of the story, comment, job, poll, or poll option to fetch the thread for."

Previous value: -"Maximum total comments to include across all depth levels. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted."New value: +"Maximum comments in one response, across all depth levels. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops at a fixed 64,000-byte text budget. When either limit stops the traversal, nextCursor continues it."

Previous value: -"Flat comment list ordered breadth-first by rank: highest-ranked top-level comments first, then their replies. Use depth/parentId to reconstruct nesting."New value: +"Flat comment list ordered breadth-first by rank: highest-ranked top-level comments first, then their replies. Use depth/parentId to reconstruct nesting. With cursor, the page continues the same order."

Previous value: -"Machine-readable failure mode. Declared by this tool: `item_not_found`: HN reports no item exists for the given itemId. `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `item_not_found`: HN reports no item exists for the given itemId. `invalid_cursor`: The cursor was issued for a different itemId than the one passed with it. `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "item_not_found",
-  "upstream_rejected",
-  "upstream_rate_limited",
-  "upstream_unavailable",
-  "upstream_html",
-  "upstream_malformed"
-]New value: +[
+  "item_not_found",
+  "invalid_cursor",
+  "upstream_rejected",
+  "upstream_rate_limited",
+  "upstream_unavailable",
+  "upstream_html",
+  "upstream_malformed"
+]

Added value: +{
+  "description": "Comment and poll-option IDs whose fetch failed after retries, so neither they nor their replies are in this response. They are not deleted or missing and may load on a later call. Failed comments ride in nextCursor and are retried when you continue; without one, call again, or pass an ID as itemId to fetch that comment and its replies. Absent when everything the traversal reached loaded.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

Previous value: -"The root item (story, comment, or poll)."New value: +"The root item: a story, comment, job, poll, or poll option."

Added value: +{
+  "const": true,
+  "description": "Present and `true` when the root is dead (flagged or killed); its replies are still walked. Omitted otherwise.",
+  "type": "boolean"
+}

Added value: +{
+  "const": true,
+  "description": "Present and `true` when HN reports the root deleted; its author and text are gone, but its replies are still walked. Omitted otherwise.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "For a poll root, its options with text and votes in parts order, resolved at every depth including 0. Deleted and dead options are kept and marked; an option whose fetch failed is listed in failedIds instead. Options do not count toward maxComments or totalLoaded.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One poll option.",
+    "properties": {
+      "dead": {
+        "const": true,
+        "description": "Present and `true` when the option is dead (flagged or killed). Omitted otherwise.",
+        "type": "boolean"
+      },
+      "deleted": {
+        "const": true,
+        "description": "Present and `true` when the option was deleted. Omitted otherwise.",
+        "type": "boolean"
+      },
+      "id": {
+        "description": "Poll option ID.",
+        "type": "number"
+      },
+      "score": {
+        "description": "Votes for this option.",
+        "type": "number"
+      },
+      "text": {
+        "description": "Option text (HTML stripped). Absent once deleted.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "For a comment root, the ID of the story or comment it replies to — pass it as itemId for the context above.",
+  "type": "number"
+}

Added value: +{
+  "description": "For a poll root, its option IDs in HN order.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "For a poll-option root, the ID of its poll.",
+  "type": "number"
+}

Previous value: -"Story/job title."New value: +"Story/job/poll title."

Added value: +{
+  "description": "Pass as cursor, with the same itemId, to continue from the next unseen comment. Present when truncationReason is count, size, or rate_limited; absent on the last page.",
+  "type": "string"
+}

Previous value: -"Truncation context: counts of deleted/dead comments dropped during traversal, then either how to get past the maxComments cap when it stopped the traversal, or a raise-maxComments-or-depth hint when totalLoaded < totalAvailable. Absent when no comments were dropped and all available comments were loaded."New value: +"Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, or rate-limit stop, or a larger depth or a comment id as itemId for a depth cut. Absent when nothing was dropped, failed, or left unread."

Previous value: -"Total comment count from the root item. If totalLoaded < totalAvailable, raise maxComments (and depth, if you want nested replies) and call again."New value: +"HN's total comment count for the root (descendants), which also counts dead and deleted comments. Absent for comment and job roots."

Previous value: -"Number of comments actually fetched and included."New value: +"Number of comments in this response (this page, when paging with cursor)."

Previous value: -"True when maxComments stopped the traversal while comments remained. Absent when every available comment was loaded, even at exactly maxComments."New value: +"True when comments remain unread: reachable through nextCursor (truncationReason count, size, or rate_limited), or below the depth limit (depth). Absent on a terminal page — including a thread that loads in full at exactly maxComments."

Added value: +{
+  "description": "Why the traversal stopped short: count = maxComments (or the 1,000-item ceiling per call) was reached; size = the 64,000-byte response budget was reached; rate_limited = the HN API throttled the fetches; depth = replies lie below the depth limit, which nextCursor does not reach — raise depth or pass a comment id as itemId. When a cursor reason and a depth cut both apply, the cursor reason is reported.",
+  "enum": [
+    "count",
+    "size",
+    "depth",
+    "rate_limited"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Submission IDs in this window whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry with the same submissionOffset, or pass an ID to hn_get_thread to fetch that item alone. Absent when every submission in the window loaded.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

Previous value: -"Pagination context — which window of the history this page covers and the submissionOffset to send next, or a warning that the offset is past the end. Absent when the page reaches the end of the history, or when no submissions were resolved."New value: +"Pagination context — which window of the history this page covers and the submissionOffset to send next, the submission IDs that failed to load and how to retry them, or a warning that the offset is past the end. Absent when the page reaches the end of the history with no failed IDs, or when no submissions were resolved."

Previous value: -"One page of submissions, most recent first, starting at submissionOffset. Absent when includeSubmissions is false or the user has never submitted. Empty when the page holds no live items — either the offset is past the end, or every item in the window was deleted or flagged."New value: +"One page of submissions, most recent first, starting at submissionOffset. Absent when includeSubmissions is false or the user has never submitted. Empty when the page holds no live items — either the offset is past the end, or every item in the window was deleted, flagged, or failed to load (failedIds lists the failures)."

Previous value: -"A single submission by the user (story, comment, job, or poll)."New value: +"A single submission by the user (story, comment, job, poll, or poll option)."

Added value: +{
+  "description": "For a comment, the ID of the story or comment it replied to — pass it to hn_get_thread for the context.",
+  "type": "number"
+}

Added value: +{
+  "description": "For a poll option, the ID of its poll.",
+  "type": "number"
+}

Previous value: -"Item type (story, comment, job, poll)."New value: +"Item type (story, comment, job, poll, pollopt)."

Previous value: -"Recovery hint when a page is empty — e.g. offset past end of feed or feed has no items. Absent on non-empty result pages."New value: +"Agent guidance: the offset to pass for the next page while more stories remain, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result."

Previous value: -"True when the feed was capped by the count parameter."New value: +"True when more stories remain beyond this page (hasMore). Absent on the last page of the feed."

Previous value: -"Truncation context: counts of deleted/dead comments dropped during traversal, or pagination hint when totalLoaded < totalAvailable. Absent when no comments were dropped and all available comments were loaded."New value: +"Truncation context: counts of deleted/dead comments dropped during traversal, then either how to get past the maxComments cap when it stopped the traversal, or a raise-maxComments-or-depth hint when totalLoaded < totalAvailable. Absent when no comments were dropped and all available comments were loaded."

Previous value: -"True when the comment list was capped by maxComments."New value: +"True when maxComments stopped the traversal while comments remained. Absent when every available comment was loaded, even at exactly maxComments."

Previous value: -"Filter to a date window. Useful for finding discussions about recent events."New value: +"Filter to a creation-time window with a start, an end, or both. An empty object is rejected — omit dateRange instead."

Previous value: -"End date (ISO 8601). Results created before this date."New value: +"Exclusive upper bound — only items created strictly before this instant match. Same formats and UTC reading as start, and must be later than start. A date-only end excludes that whole UTC day: to include it, pass the next day or a full timestamp."

Added value: +"^(\\d{4})(?:-(\\d{2})(?:-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,3})?)?(?:Z|[+-](\\d{2}):(\\d{2}))?)?)?)?$"

Previous value: -"Start date (ISO 8601). Results created after this date."New value: +"Exclusive lower bound — only items created strictly after this instant match. ISO 8601: YYYY, YYYY-MM, YYYY-MM-DD, or YYYY-MM-DDThh:mm[:ss[.sss]] with an optional Z or ±hh:mm offset. Reduced and date-only forms mean UTC midnight at the start of that period; a date-time without an offset is read as UTC."

Added value: +"^(\\d{4})(?:-(\\d{2})(?:-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,3})?)?(?:Z|[+-](\\d{2}):(\\d{2}))?)?)?)?$"

Previous value: -"Minimum score/points. Filters out low-engagement content."New value: +"Minimum score. Applies to stories and polls, including the ask_hn, show_hn, and front_page subsets. Comments and jobs carry no points in the search index, so any minPoints excludes them — combining it with tags \"comment\" or \"job\" is rejected."

Previous value: -"Search terms. Supports simple keywords — Algolia handles stemming and relevance. Trimmed before searching; blank or whitespace-only input is rejected."New value: +"Search terms. Supports simple keywords — Algolia handles stemming and relevance. Trimmed before searching; blank or whitespace-only input is rejected. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound."

Added value: +{
+  "description": "Restrict results to one discussion: the id of a story or poll root, combined with the other filters. Pair with tags \"comment\" to search within a thread. Take it from hits[].storyId or the root item of hn_get_thread — a comment id matches nothing.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

Previous value: -"Filter results by content type. Omit to search all types."New value: +"Filter results by content type: \"story\", \"comment\", \"poll\", or \"job\", or the story subsets \"ask_hn\", \"show_hn\", and \"front_page\". Omit to search all types."

Previous value: -[
-  "story",
-  "comment",
-  "ask_hn",
-  "show_hn",
-  "front_page"
-]New value: +[
+  "story",
+  "comment",
+  "poll",
+  "job",
+  "ask_hn",
+  "show_hn",
+  "front_page"
+]

Removed value: -[
-  "query"
-]

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "hits",
-      "query",
-      "totalHits",
-      "page",
-      "totalPages"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "hits",
+      "totalHits",
+      "page",
+      "totalPages"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_rejected`: Algolia answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: Algolia answered with HTTP 429. `upstream_unavailable`: Algolia answered with a 5xx status. `upstream_html`: Algolia served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: Algolia answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_query_or_filter`: Neither a query nor any filter was supplied, so there is nothing to search by. `invalid_date_range`: dateRange was supplied with neither bound, or with start not before end. `min_points_unscored_type`: minPoints was combined with tags \"comment\" or \"job\", record types Algolia stores without points. `upstream_rejected`: Algolia answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: Algolia answered with HTTP 429. `upstream_unavailable`: Algolia answered with a 5xx status. `upstream_html`: Algolia served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: Algolia answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "upstream_rejected",
-  "upstream_rate_limited",
-  "upstream_unavailable",
-  "upstream_html",
-  "upstream_malformed"
-]New value: +[
+  "missing_query_or_filter",
+  "invalid_date_range",
+  "min_points_unscored_type",
+  "upstream_rejected",
+  "upstream_rate_limited",
+  "upstream_unavailable",
+  "upstream_html",
+  "upstream_malformed"
+]

Previous value: -"A single Algolia search hit (story or comment)."New value: +"A single Algolia search hit (story, comment, poll, or job)."

Previous value: -"Story title (present for stories)."New value: +"Item title (present for stories, polls, and jobs)."

Previous value: -"Recovery hint when results are empty — names the filters applied, for relaxing the search. Absent on non-empty result pages."New value: +"Agent guidance: the next page to request while more pages remain, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Absent on the last page of a non-empty result."

Previous value: -"The query that was searched."New value: +"The query that was searched. Absent for a filter-only search."

Previous value: -"True when the hit list was capped by the count parameter."New value: +"True when more pages remain after this one (page + 1 < totalPages). Absent on the last page Algolia serves."

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "stories",
+      "feed",
+      "total",
+      "offset",
+      "hasMore"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "upstream_rejected",
+            "upstream_rate_limited",
+            "upstream_unavailable",
+            "upstream_html",
+            "upstream_malformed"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "stories",
-  "feed",
-  "total",
-  "offset",
-  "hasMore"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "item",
+      "comments",
+      "totalLoaded"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `item_not_found`: HN reports no item exists for the given itemId. `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "item_not_found",
+            "upstream_rejected",
+            "upstream_rate_limited",
+            "upstream_unavailable",
+            "upstream_html",
+            "upstream_malformed"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "item",
-  "comments",
-  "totalLoaded"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "user"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `user_not_found`: HN reports no user account exists for the given username. `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built, which a username outside HN’s charset can cause. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "user_not_found",
+            "upstream_rejected",
+            "upstream_rate_limited",
+            "upstream_unavailable",
+            "upstream_html",
+            "upstream_malformed"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "user"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "hits",
+      "query",
+      "totalHits",
+      "page",
+      "totalPages"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `upstream_rejected`: Algolia answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: Algolia answered with HTTP 429. `upstream_unavailable`: Algolia answered with a 5xx status. `upstream_html`: Algolia served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: Algolia answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "upstream_rejected",
+            "upstream_rate_limited",
+            "upstream_unavailable",
+            "upstream_html",
+            "upstream_malformed"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "hits",
-  "query",
-  "totalHits",
-  "page",
-  "totalPages"
-]

Previous value: -"Number of recent submissions to resolve. Only used when includeSubmissions is true."New value: +"Page size — how many submissions to resolve per call. Only used when includeSubmissions is true."

Added value: +{
+  "default": 0,
+  "description": "How many submissions to skip before resolving, counting back from the most recent. Use with submissionCount to page through a long history: request offset 0, then offset submissionCount, and so on. The enrichment block echoes submissionOffset and, when more remain, the offset to send next. Only used when includeSubmissions is true.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

Previous value: -"Pagination caveat when submissions were truncated. Absent when all submissions fit within the requested count or includeSubmissions is false."New value: +"Pagination context — which window of the history this page covers and the submissionOffset to send next, or a warning that the offset is past the end. Absent when the page reaches the end of the history, or when no submissions were resolved."

Added value: +{
+  "description": "The offset this page started at. Absent when includeSubmissions is false or the user has never submitted.",
+  "type": "number"
+}

Previous value: -"Recent submissions, most recent first. Only present when includeSubmissions is true."New value: +"One page of submissions, most recent first, starting at submissionOffset. Absent when includeSubmissions is false or the user has never submitted. Empty when the page holds no live items — either the offset is past the end, or every item in the window was deleted or flagged."

Previous value: -"True when submissions were capped by submissionCount."New value: +"True when submissions remain beyond this page."

Added value: +{
+  "default": "full",
+  "description": "How much of each hit to return. \"full\" includes every field. \"compact\" omits the two body-text fields — `text` and `highlights.text` — which together can repeat a long comment twice per hit; everything else (id, title, url, domain, author, points, comment count, timestamp, parent story, title highlight, matchedWords) is unchanged. Use \"compact\" to scan many results, then pass a hit id to hn_get_thread to read the body you skipped.",
+  "enum": [
+    "full",
+    "compact"
+  ],
+  "type": "string"
+}

Previous value: -"Body snippet (comment_text or story_text) with matched terms wrapped in `<em>…</em>`. Absent when the body did not match."New value: +"Body snippet (comment_text or story_text) with matched terms wrapped in `<em>…</em>`. Absent when the body did not match, and always absent under view \"compact\" — matchedWords still lists what matched."

Previous value: -"Comment or story body text (HTML stripped)."New value: +"Comment or story body text (HTML stripped). Absent when the hit has no body, and always absent under view \"compact\" — call hn_get_thread with this id to read it."

Previous value: -"number"New value: +"integer"

Added value: +9007199254740991

Previous value: -"number"New value: +"integer"

Previous value: -"number"New value: +"integer"

Added value: +9007199254740991

Added value: +-9007199254740991

Previous value: -"number"New value: +"integer"

Previous value: -"number"New value: +"integer"

Previous value: -"number"New value: +"integer"

Previous value: -"HN username. Case-sensitive."New value: +"HN username. Case-sensitive. Trimmed; blank or whitespace-only input is rejected."

Previous value: -"Filter results to a specific author. Useful for finding a user's posts on a topic (hn_get_user only shows recent submissions)."New value: +"Filter results to a specific author. Useful for finding a user's posts on a topic (hn_get_user only shows recent submissions). Trimmed before filtering; omit the field to search all authors rather than passing a blank string."

Added value: +1

Previous value: -"number"New value: +"integer"

Added value: +9007199254740991

Previous value: -"number"New value: +"integer"

Added value: +9007199254740991

Previous value: -"number"New value: +"integer"

Previous value: -"Search terms. Supports simple keywords — Algolia handles stemming and relevance."New value: +"Search terms. Supports simple keywords — Algolia handles stemming and relevance. Trimmed before searching; blank or whitespace-only input is rejected."

Added value: +1

Previous value: -"Total pages available."New value: +"Number of pages Algolia will actually serve for this query. Not derived from totalHits — broad queries report a totalHits far larger than the reachable page range, so paginate against this value."

Added value: +{
+  "description": "The count cap that was applied.",
+  "type": "number"
+}

Added value: +{
+  "description": "Number of stories returned on this page.",
+  "type": "number"
+}

Added value: +{
+  "description": "True when the feed was capped by the count parameter.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "The maxComments cap that was applied.",
+  "type": "number"
+}

Added value: +{
+  "description": "Number of comments returned.",
+  "type": "number"
+}

Added value: +{
+  "description": "True when the comment list was capped by maxComments.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "The submissionCount cap that was applied.",
+  "type": "number"
+}

Added value: +{
+  "description": "Number of submissions returned.",
+  "type": "number"
+}

Added value: +{
+  "description": "True when submissions were capped by submissionCount.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "The count cap that was applied.",
+  "type": "number"
+}

Added value: +{
+  "description": "Number of hits returned.",
+  "type": "number"
+}

Added value: +{
+  "description": "True when the hit list was capped by the count parameter.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Pagination caveat when submissions were truncated. Absent when all submissions fit within the requested count or includeSubmissions is false.",
+  "type": "string"
+}

Added value: +{
+  "description": "Recovery hint when a page is empty — e.g. offset past end of feed or feed has no items. Absent on non-empty result pages.",
+  "type": "string"
+}

Previous value: -"Offset that was applied to this page (echoes input.offset)."New value: +"Offset that was applied to this page."

Added value: +{
+  "description": "Truncation context: counts of deleted/dead comments dropped during traversal, or pagination hint when totalLoaded < totalAvailable. Absent when no comments were dropped and all available comments were loaded.",
+  "type": "string"
+}

Removed value: -{
-  "additionalProperties": false,
-  "description": "Counts of comments dropped during BFS traversal. Present only when at least one comment was dropped, so the caller can tell when a thread view is partial due to moderation rather than depth/maxComments limits. Absence means no moderation truncation.",
-  "properties": {
-    "dead": {
-      "description": "Count of comments dropped because HN flagged them dead (autoflagged).",
-      "type": "number"
-    },
-    "deleted": {
-      "description": "Count of comments dropped because HN flagged them deleted (author/mod removal).",
-      "type": "number"
-    }
-  },
-  "required": [
-    "deleted",
-    "dead"
-  ],
-  "type": "object"
-}

Removed value: -{
-  "description": "Recovery hint when results are empty — names the filters that were applied, for relaxing the search. Absent on non-empty result pages.",
-  "type": "string"
-}

Added value: +{
+  "description": "Recovery hint when results are empty — names the filters applied, for relaxing the search. Absent on non-empty result pages.",
+  "type": "string"
+}

Previous value: -"Current page number."New value: +"Current page number (0-indexed)."

Previous value: -[
-  "hits",
-  "totalHits",
-  "page",
-  "totalPages",
-  "query"
-]New value: +[
+  "hits",
+  "query",
+  "totalHits",
+  "page",
+  "totalPages"
+]