@cyanheads/hn-mcp-server 0.5.21 → 0.5.22

package/dist/mcp-server/tools/definitions/search-content.tool.js

@@ -5,9 +5,45 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { escapeHighlight, escapeInline, escapeQuoted, quoteBody, } from '../markdown-escape.js';
-import { dateBoundToEpochMs, decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, stripHtml, stripHtmlPreservingEm, } from '../../../services/hn/hn-service.js';
-/** Largest page `count` accepts, mirrored in the input schema. */
-const MAX_COUNT = 50;
+import { servedAtCap } from '../served-at-cap.js';
+import { dateBoundToEpochMs, dateRangeToEpochSeconds, decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, stripHtml, stripHtmlPreservingEm, } from '../../../services/hn/hn-service.js';
+/** Most hits one call serves; a larger `count` is served at this cap. */
+const COUNT_CAP = 50;
+/** Largest `count` accepted; anything above it is rejected. */
+const COUNT_CEILING = 1000;
+/**
+ * The recovery for a first hit no page of 50 begins on: the largest count up to
+ * the cap whose pages include one starting at that hit, so a caller can resume
+ * from exactly there. When that count is under half the cap, covering a cap's
+ * worth of hits from there takes three or more calls where pages of 50 take
+ * two, so the page of 50 holding the hit is named as well.
+ */
+function unalignedHint(firstHit) {
+    let size = COUNT_CAP;
+    while (firstHit % size !== 0)
+        size--;
+    const exact = `Pass count: ${size}, page: ${firstHit / size} to start at the same hit`;
+    if (size * 2 >= COUNT_CAP)
+        return `${exact}.`;
+    const page = Math.floor(firstHit / COUNT_CAP);
+    const start = page * COUNT_CAP;
+    return `${exact}, or count: ${COUNT_CAP}, page: ${page} for hits ${start}–${start + COUNT_CAP - 1}, which include hit ${firstHit}.`;
+}
+/** Algolia serves at most this many hits per search, however many match. */
+const HIT_CEILING = 1000;
+/** The content types `tags` accepts. */
+const SEARCH_TAGS = ['story', 'comment', 'poll', 'job', 'ask_hn', 'show_hn', 'front_page'];
+/** The item types a hit's `_tags` can name. `ask_hn`, `show_hn`, and `front_page` are further tags on a story. */
+const HIT_TYPES = ['story', 'comment', 'poll', 'pollopt', 'job'];
+/**
+ * The first `_tags` entry that names an item type, or undefined when none does.
+ * The first match, not the first entry, so a reordered tag list cannot mistype
+ * a hit. A poll option's `story_<id>` tag, where present, names the option
+ * itself, so no parent is read from it.
+ */
+function hitType(tags) {
+    return tags?.find((tag) => HIT_TYPES.includes(tag));
+}
 /**
  * ISO 8601 calendar forms accepted for a date bound: `YYYY`, `YYYY-MM`,
  * `YYYY-MM-DD`, or `YYYY-MM-DDThh:mm[:ss[.sss]]` with an optional `Z` or
@@ -46,6 +82,70 @@ const dateBound = () => z
     .regex(DATE_BOUND_PATTERN, 'must be an ISO 8601 date or date-time — YYYY, YYYY-MM, YYYY-MM-DD, or YYYY-MM-DDThh:mm[:ss[.sss]] with an optional Z or ±hh:mm offset.')
     .refine(isCalendarValid, 'is not a real calendar date or time — check the month, day, hour, minute, second, and offset ranges.')
     .optional();
+/** A URL's scheme and `www.`, or a bare leading `www.`. Anchored, so it reads a fixed-length prefix at most. */
+const URL_PREFIX = /^(?:https?:\/\/(?:www\.)?|www\.)/i;
+/**
+ * Drop the scheme and `www.` from a query that is a URL alone. Algolia requires
+ * every token, so `https` and `www` would otherwise have to appear in the
+ * submitted URL, and the same page submitted under the other scheme or without
+ * `www.` would drop out. A query with whitespace is searched as typed, and so
+ * is one the prefix would leave empty.
+ */
+export function stripUrlPrefix(query) {
+    if (/\s/.test(query))
+        return { query };
+    const prefix = URL_PREFIX.exec(query)?.[0];
+    if (prefix == null || prefix.length === query.length)
+        return { query };
+    return { query: query.slice(prefix.length), droppedPrefix: prefix };
+}
+/** The search as run: the filters set, then sort, count, and view with their defaults. */
+const searchCriteria = z
+    .object({
+    tags: z.enum(SEARCH_TAGS).optional().describe('Content-type filter.'),
+    author: z.string().optional().describe('Author filter — the username matched, trimmed.'),
+    storyId: z.number().optional().describe('Discussion filter: a story or poll root id.'),
+    minPoints: z.number().optional().describe('Minimum score.'),
+    dateRange: z
+        .object({
+        start: z
+            .string()
+            .optional()
+            .describe('Items match only when created strictly after this instant: the start bound in ISO 8601 UTC, rounded down to the whole second.'),
+        end: z
+            .string()
+            .optional()
+            .describe('Items match only when created strictly before this instant: the end bound in ISO 8601 UTC, rounded up to the whole second.'),
+    })
+        .optional()
+        .describe('Creation-time window as applied, with only the bounds that were set.'),
+    sort: z.enum(['relevance', 'date']).describe('Sort order used.'),
+    count: z
+        .number()
+        .describe('Hits per page sent: count as passed, or 50 when count was above that cap.'),
+    view: z.enum(['full', 'compact']).describe('Projection applied to each hit.'),
+})
+    .describe('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.');
+/** A whole Unix second as ISO 8601 UTC, e.g. `2024-05-05T08:00:00Z`. */
+const isoSeconds = (seconds) => new Date(seconds * 1000).toISOString().replace('.000Z', 'Z');
+/** One trailer line for the criteria; `author`, the one free-text value, is escaped inside its quotes. */
+function renderCriteria(c) {
+    const bounds = c.dateRange && [
+        c.dateRange.start != null ? `after ${c.dateRange.start}` : null,
+        c.dateRange.end != null ? `before ${c.dateRange.end}` : null,
+    ];
+    const parts = [
+        c.tags != null ? `tags: ${c.tags}` : null,
+        c.author != null ? `author: "${escapeQuoted(c.author)}"` : null,
+        c.storyId != null ? `storyId: ${c.storyId}` : null,
+        c.minPoints != null ? `minPoints: ${c.minPoints}` : null,
+        bounds ? `dateRange: ${bounds.filter(Boolean).join(', ')}` : null,
+        `sort: ${c.sort}`,
+        `count: ${c.count}`,
+        `view: ${c.view}`,
+    ];
+    return `**criteria:** ${parts.filter(Boolean).join(' | ')}`;
+}
 /** The filters a caller set, in the order notices name them. `sort`, `count`, `page`, and `view` are not filters. */
 function appliedFilters(input) {
     const filters = [];
@@ -62,25 +162,90 @@ function appliedFilters(input) {
     return filters;
 }
 /**
- * Notice for a page that came back empty. A page past the end names the last
- * valid page when Algolia reports one; past its 1,000-hit ceiling Algolia
- * answers `nbPages: 0`, so the last page is unknown and the notice resets to
- * page 0. Only a first page with no hits is a zero-match search.
+ * The page-state sentence. A non-empty page names the next page while more
+ * remain, and the last page of a search matching more than Algolia serves names
+ * that ceiling. An empty page past the end names the last valid page when
+ * Algolia reports one; past the ceiling Algolia answers `nbPages: 0`, so the
+ * last page is unknown and the notice resets to page 0. Only a first page with
+ * no hits is a zero-match search, which names what to relax. After a count
+ * above the cap, a page lever also names the count it counts in.
  */
-function emptyPageNotice(input, filters, page, totalHits, totalPages) {
+function pageStateSentence(facts) {
+    const { shown, page, totalHits, totalPages } = facts;
+    const pageLever = (n) => `${facts.overCap ? `count: ${facts.count}, ` : ''}page: ${n}`;
+    if (shown > 0) {
+        const total = `${facts.totalHitsExact === false ? 'about ' : ''}${totalHits}`;
+        if (page + 1 < totalPages) {
+            const raiseCount = facts.count < COUNT_CAP ? `, or raise count (max ${COUNT_CAP})` : '';
+            return `Showing ${shown} of ${total} hits (page ${page} of ${totalPages}). Pass ${pageLever(page + 1)} for more${raiseCount}.`;
+        }
+        return totalHits > HIT_CEILING
+            ? `Page ${page} is the last page Algolia serves: a search returns at most 1,000 of its matches, and this one matches ${total}. Split it into narrower dateRange windows to reach the rest.`
+            : undefined;
+    }
     if (page > 0) {
-        return totalPages > 0
-            ? `Page ${page} is past the last page of results (${totalHits} hits across ${totalPages} page${totalPages === 1 ? '' : 's'}). Pass page: ${totalPages - 1} for the last page, or page: 0 to start over.`
-            : `Page ${page} is past the last page Algolia serves for this search (at most 1,000 hits per search), where totalHits and totalPages read 0. Pass page: 0 to start over; if that also returns nothing, the search itself matches nothing.`;
+        if (totalPages === 0) {
+            return `Page ${page} is past the last page Algolia serves for this search (at most 1,000 hits per search), where totalHits and totalPages read 0. Pass page: 0 to start over; if that also returns nothing, the search itself matches nothing.`;
+        }
+        /** With one page, the last page is page 0, so one lever covers both. */
+        const lever = totalPages === 1
+            ? `Pass ${pageLever(0)} for that page.`
+            : `Pass ${pageLever(totalPages - 1)} for the last page, or page: 0 to start over.`;
+        return `Page ${page} is past the last page of results (${totalHits} hits across ${totalPages} page${totalPages === 1 ? '' : 's'}). ${lever}`;
+    }
+    const filters = appliedFilters(facts);
+    if (facts.query == null) {
+        return `No items matched these filters: ${filters.join(', ')}. Relax or change them.`;
+    }
+    return filters.length
+        ? `Try broader keywords, or relax these filters: ${filters.join(', ')}.`
+        : 'Try broader keywords or different terms.';
+}
+/**
+ * Sentences an input calls for, in input order: query, tags, author, storyId,
+ * then count when it was above the per-call cap — said when hits remain past
+ * the served page, or when the served page is numbered differently from the
+ * one requested.
+ */
+function causeSentences(facts) {
+    const emptyFirstPage = facts.shown === 0 && facts.page === 0;
+    const sentences = [];
+    if (facts.droppedPrefix != null) {
+        sentences.push(`The leading \`${facts.droppedPrefix}\` was dropped from the query, so the URL matches submissions under either scheme, with or without www.`);
+        if (emptyFirstPage) {
+            sentences.push('Submissions often omit #fragments and tracking parameters such as utm_source; search the URL without them.');
+        }
+    }
+    if (facts.tags === 'front_page' &&
+        (emptyFirstPage || facts.dateRange?.start || facts.dateRange?.end)) {
+        sentences.push('front_page matches only the stories on the HN front page right now (about 30), never past front pages; for an earlier window, search tags "story" with dateRange and minPoints instead.');
     }
-    const base = input.query == null
-        ? `No items matched these filters: ${filters.join(', ')}. Relax or change them.`
-        : filters.length
-            ? `Try broader keywords, or relax these filters: ${filters.join(', ')}.`
-            : 'Try broader keywords or different terms.';
-    return input.storyId == null
-        ? base
-        : `${base} storyId must be a story or poll root id — take it from hits[].storyId or the hn_get_thread root; a comment id matches nothing.`;
+    if (emptyFirstPage && facts.author) {
+        sentences.push("author must match the username's exact HN casing; hn_get_user answers user_not_found for a mis-cased name.");
+    }
+    if (emptyFirstPage && facts.storyId != null) {
+        sentences.push("storyId must be a story or poll root id — take it from hits[].storyId, a poll hit's own id (poll hits carry no storyId), or hn_get_thread: the root item's id, or its item.storyId when the root is a comment. A comment id matches nothing.");
+    }
+    const { overCap } = facts;
+    const morePages = facts.shown > 0 && facts.page + 1 < facts.totalPages;
+    if (overCap && (morePages || overCap.page > 0)) {
+        sentences.push(servedAtCap('count', overCap.count, facts.count));
+        if (overCap.page > 0) {
+            sentences.push(`Page ${overCap.page} at count ${overCap.count} starts at the same hit as page ${facts.page} at count ${facts.count}, the page served.`);
+        }
+    }
+    return sentences;
+}
+/**
+ * Compose the one `notice` string every search writes. `notice` is last-wins,
+ * so each source goes through here: the page-state sentence first, then the
+ * cause sentences in input order — query, tags, author, storyId, count. None
+ * replaces another. Undefined when nothing applies — the last page of an
+ * uncapped, non-empty search.
+ */
+export function composeSearchNotice(facts) {
+    const sentences = [pageStateSentence(facts), ...causeSentences(facts)].filter((sentence) => sentence != null);
+    return sentences.length > 0 ? sentences.join(' ') : undefined;
 }
 /**
  * Entity-decode a title highlight between its `<em>` markers. A decoded
@@ -95,9 +260,10 @@ function decodeHighlightTitle(title) {
 }
 /**
  * Project Algolia's `_highlightResult` into a flat snippet object: the title
- * snippet, the body snippet (preferring comment_text over story_text to match
- * the `text` mapping), and the deduplicated union of matched words across all
- * surfaced fields. Returns undefined when nothing matched.
+ * snippet, the body snippet (comment_text, else story_text — the order `text`
+ * reads them in; a job's job_text is never highlighted), and the deduplicated
+ * union of matched words across all surfaced fields. Returns undefined when
+ * nothing matched.
  *
  * Titles are not HTML, though some arrive entity-encoded (`&lt;details&gt;`,
  * `&#34;`), so the title snippet is entity-decoded between its `<em>` markers
@@ -154,6 +320,13 @@ export const searchHn = tool('hn_search_content', {
             recovery: 'Drop minPoints to search comments or jobs, or search a scored type (story, poll, ask_hn, show_hn, front_page) to filter by points.',
             severity: 'notice',
         },
+        {
+            reason: 'count_page_unaligned',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: '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.',
+            recovery: 'Pass a count of 50 or less with page counted in that count; the error names a count and page that start at the same hit and, when that count is under 25, the page of 50 that holds the hit.',
+            severity: 'notice',
+        },
         {
             reason: 'upstream_rejected',
             code: JsonRpcErrorCode.InvalidParams,
@@ -200,23 +373,23 @@ export const searchHn = tool('hn_search_content', {
             .trim()
             .min(1, 'blank after trimming whitespace — pass one or more search terms, or omit query for a filter-only search.')
             .optional()
-            .describe('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.'),
+            .describe('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.'),
         tags: z
-            .enum(['story', 'comment', 'poll', 'job', 'ask_hn', 'show_hn', 'front_page'])
+            .enum(SEARCH_TAGS)
             .optional()
-            .describe('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.'),
+            .describe('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.'),
         author: z
             .string()
             .trim()
             .min(1, 'blank after trimming whitespace — omit author to search all authors.')
             .optional()
-            .describe(`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.`),
+            .describe(`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.`),
         storyId: z
             .number()
             .int()
             .positive()
             .optional()
-            .describe('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.'),
+            .describe('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.'),
         sort: z
             .enum(['relevance', 'date'])
             .default('relevance')
@@ -238,10 +411,15 @@ export const searchHn = tool('hn_search_content', {
             .number()
             .int()
             .min(1)
-            .max(MAX_COUNT)
+            .max(COUNT_CEILING)
             .default(30)
-            .describe('Number of results to return.'),
-        page: z.number().int().min(0).default(0).describe('Page number for pagination (0-indexed).'),
+            .describe(`Number of results to return, at most ${COUNT_CAP} per call. A larger value is served at ${COUNT_CAP}: the search runs at count ${COUNT_CAP} 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 ${COUNT_CAP} hits.`),
+        page: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe('Page number for pagination (0-indexed), counted in pages of count results.'),
         view: z
             .enum(['full', 'compact'])
             .default('full')
@@ -252,6 +430,10 @@ export const searchHn = tool('hn_search_content', {
             .array(z
             .object({
             id: z.number().describe('HN item ID — use with hn_get_thread to read the discussion.'),
+            type: z
+                .enum(HIT_TYPES)
+                .optional()
+                .describe('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.'),
             title: z
                 .string()
                 .optional()
@@ -272,11 +454,11 @@ export const searchHn = tool('hn_search_content', {
             storyId: z
                 .number()
                 .optional()
-                .describe('Parent story ID for comment hits; equals `id` for story hits.'),
+                .describe("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."),
             text: z
                 .string()
                 .optional()
-                .describe('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.'),
+                .describe("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."),
             highlights: z
                 .object({
                 title: z
@@ -294,29 +476,48 @@ export const searchHn = tool('hn_search_content', {
                 .optional()
                 .describe('Algolia per-field highlight metadata showing which terms matched and where. Absent when no fields produced a match.'),
         })
-            .describe('A single Algolia search hit (story, comment, poll, or job).'))
+            .describe('A single Algolia search hit (story, comment, poll, poll option, or job).'))
             .describe('Search results ranked by sort order.'),
         query: z
             .string()
             .optional()
-            .describe('The query that was searched. Absent for a filter-only search.'),
+            .describe('The query that was searched — for a URL query, without its leading scheme and www. Absent for a filter-only search.'),
     }),
     enrichment: {
-        totalHits: z.number().describe('Total matching results across all pages.'),
-        page: z.number().describe('Current page number (0-indexed).'),
+        criteria: searchCriteria,
+        totalHits: z
+            .number()
+            .describe('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).'),
+        totalHitsExact: z
+            .boolean()
+            .optional()
+            .describe('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.'),
+        page: z
+            .number()
+            .describe('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.'),
         totalPages: z
             .number()
-            .describe('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.'),
+            .describe('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.'),
+        reachableHits: z
+            .number()
+            .optional()
+            .describe('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.'),
         truncated: z
             .boolean()
             .optional()
             .describe('True when more pages remain after this one (page + 1 < totalPages). Absent on the last page Algolia serves.'),
         shown: z.number().optional().describe('Number of hits returned.'),
-        cap: z.number().optional().describe('The count cap that was applied.'),
+        cap: z
+            .number()
+            .optional()
+            .describe(`The count value served: as passed, or ${COUNT_CAP} when count was above that cap.`),
         notice: z
             .string()
             .optional()
-            .describe('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.'),
+            .describe('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.'),
+    },
+    enrichmentTrailer: {
+        criteria: { render: renderCriteria },
     },
     async handler(input, ctx) {
         const { dateRange } = input;
@@ -336,16 +537,32 @@ export const searchHn = tool('hn_search_content', {
         if (input.query == null && filters.length === 0) {
             throw ctx.fail('missing_query_or_filter', 'No query and no filter were supplied, so there is nothing to search by.');
         }
+        /** Above the cap, the search runs at the cap from the hit where the requested page starts. */
+        const overCap = input.count > COUNT_CAP ? { count: input.count, page: input.page } : undefined;
+        const firstHit = input.page * input.count;
+        if (overCap && firstHit % COUNT_CAP !== 0) {
+            throw ctx.fail('count_page_unaligned', `count ${input.count} is above the per-call cap of ${COUNT_CAP}, and page ${input.page} at count ${input.count} starts after ${firstHit} hits, where no page of ${COUNT_CAP} hits begins.`, { count: input.count, page: input.page, recovery: { hint: unalignedHint(firstHit) } });
+        }
+        const searched = input.query == null ? undefined : stripUrlPrefix(input.query);
+        const params = {
+            ...input,
+            ...(searched && { query: searched.query }),
+            ...(overCap && { count: COUNT_CAP, page: firstHit / COUNT_CAP }),
+        };
         const hn = getHnService();
-        const result = await hn.search(input, ctx);
+        const result = await hn.search(params, ctx);
         const includeBody = input.view === 'full';
         const hits = result.hits.map((hit) => {
-            const rawText = includeBody ? (hit.comment_text ?? hit.story_text) : undefined;
+            const rawText = includeBody
+                ? (hit.comment_text ?? hit.story_text ?? hit.job_text)
+                : undefined;
             const url = normalizeUrl(hit.url);
             const domain = extractDomain(url);
             const highlights = extractHighlights(hit, includeBody);
+            const type = hitType(hit._tags);
             return {
                 id: Number(hit.objectID),
+                ...(type && { type }),
                 title: hit.title != null ? decodeHtmlEntities(hit.title) : undefined,
                 url,
                 domain,
@@ -360,26 +577,57 @@ export const searchHn = tool('hn_search_content', {
             };
         });
         ctx.log.info('Search completed', {
-            query: input.query,
+            query: params.query,
             hits: hits.length,
             totalHits: result.nbHits,
         });
         const { nbHits: totalHits, nbPages: totalPages, page } = result;
-        ctx.enrich({ totalHits, page, totalPages });
-        if (hits.length === 0) {
-            ctx.enrich.notice(emptyPageNotice(input, filters, page, totalHits, totalPages));
-        }
-        else if (page + 1 < totalPages) {
-            const raiseCount = input.count < MAX_COUNT ? `, or raise count (max ${MAX_COUNT})` : '';
-            ctx.enrich.truncated({
-                shown: hits.length,
-                cap: input.count,
-                guidance: `Showing ${hits.length} of ${totalHits} hits (page ${page} of ${totalPages}). Pass page: ${page + 1} for more${raiseCount}.`,
-            });
-        }
+        const shown = hits.length;
+        /** Past the ceiling Algolia flags its 0 as exact, though it says nothing about the search. */
+        const pastCeiling = shown === 0 && page > 0 && totalPages === 0;
+        const totalHitsExact = pastCeiling
+            ? undefined
+            : (result.exhaustive?.nbHits ?? result.exhaustiveNbHits);
+        const bounds = params.dateRange ? dateRangeToEpochSeconds(params.dateRange) : {};
+        ctx.enrich({
+            criteria: {
+                ...(params.tags != null && { tags: params.tags }),
+                ...(params.author != null && { author: params.author }),
+                ...(params.storyId != null && { storyId: params.storyId }),
+                ...(params.minPoints != null && { minPoints: params.minPoints }),
+                ...((bounds.start != null || bounds.end != null) && {
+                    dateRange: {
+                        ...(bounds.start != null && { start: isoSeconds(bounds.start) }),
+                        ...(bounds.end != null && { end: isoSeconds(bounds.end) }),
+                    },
+                }),
+                sort: params.sort,
+                count: params.count,
+                view: params.view,
+            },
+            totalHits,
+            ...(totalHitsExact != null && { totalHitsExact }),
+            page,
+            totalPages,
+            ...(totalHits > HIT_CEILING && { reachableHits: HIT_CEILING }),
+        });
+        if (shown > 0 && page + 1 < totalPages)
+            ctx.enrich.truncated({ shown, cap: params.count });
+        const notice = composeSearchNotice({
+            ...params,
+            droppedPrefix: searched?.droppedPrefix,
+            shown,
+            page,
+            totalHits,
+            totalHitsExact,
+            totalPages,
+            overCap,
+        });
+        if (notice)
+            ctx.enrich.notice(notice);
         return {
             hits,
-            ...(input.query != null && { query: input.query }),
+            ...(params.query != null && { query: params.query }),
         };
     },
     format: (result) => {
@@ -387,7 +635,7 @@ export const searchHn = tool('hn_search_content', {
             return [
                 {
                     type: 'text',
-                    text: result.query != null ? `"${result.query}" — no results.` : 'No results.',
+                    text: result.query != null ? `"${escapeQuoted(result.query)}" — no results.` : 'No results.',
                 },
             ];
         }
@@ -409,6 +657,21 @@ export const searchHn = tool('hn_search_content', {
             return parts.length ? `\n\n${quoteBody(`match — ${parts.join(' | ')}`)}` : '';
         };
         const lines = result.hits.map((h) => {
+            const typeToken = h.type ? `type:${h.type}` : null;
+            const hlLine = h.highlights ? renderHighlights(h.highlights) : '';
+            if (h.type === 'pollopt') {
+                // A poll option's search record carries no text and no poll; hn_get_thread has both.
+                const meta = [
+                    `id:${h.id}`,
+                    typeToken,
+                    h.author,
+                    h.points != null ? `${h.points} pts` : null,
+                    h.createdAt,
+                ]
+                    .filter(Boolean)
+                    .join(' | ');
+                return `### Poll option by ${h.author}\n${meta}\nOption text and its poll: hn_get_thread with itemId ${h.id}${hlLine}`;
+            }
             if (h.title) {
                 // Story result — Algolia returns storyId === id for stories, so suppress the parent ref unless it actually differs or a parent title is set.
                 const parentRef = (h.storyId != null && h.storyId !== h.id) || h.storyTitle
@@ -416,6 +679,7 @@ export const searchHn = tool('hn_search_content', {
                     : '';
                 const meta = [
                     `id:${h.id}`,
+                    typeToken,
                     h.author,
                     h.points != null ? `${h.points} pts` : null,
                     h.numComments != null ? `${h.numComments} comments` : null,
@@ -426,12 +690,12 @@ export const searchHn = tool('hn_search_content', {
                 const domain = h.domain ? ` (${h.domain})` : '';
                 const url = h.url ? `\n${h.url}` : '';
                 const text = h.text ? `\n${quoteBody(h.text)}` : '';
-                const hlLine = h.highlights ? renderHighlights(h.highlights) : '';
                 return `### ${escapeInline(h.title)}${domain}\n${meta}${parentRef}${url}${text}${hlLine}`;
             }
             // Comment result — parent context in heading.
             const meta = [
                 `id:${h.id}`,
+                typeToken,
                 h.author,
                 h.points != null ? `${h.points} pts` : null,
                 h.createdAt,
@@ -439,11 +703,10 @@ export const searchHn = tool('hn_search_content', {
                 .filter(Boolean)
                 .join(' | ');
             const text = h.text ? `\n${quoteBody(h.text)}` : '';
-            const hlLine = h.highlights ? renderHighlights(h.highlights) : '';
             return `### Comment on "${escapeQuoted(h.storyTitle ?? 'unknown')}" (story id:${h.storyId ?? '?'})\n${meta}${text}${hlLine}`;
         });
         const header = result.query != null
-            ? `## "${result.query}" — search results`
+            ? `## "${escapeQuoted(result.query)}" — search results`
             : '## Search results (filters only)';
         return [{ type: 'text', text: `${header}\n\n${lines.join('\n\n')}` }];
     },