fix: Report an empty search-actors page past the last result as such (#1568)

## Why

Closes #1276

Review page with before/after examples for this PR and the five related
ones (#1563–#1567): https://claude.ai/artifact/WDRj1nwPnMTP9ktGyg3z3i

Reported by @lokicik. This follows the implementation spec in the
maintainer comment on the issue.

`search-actors` returned the no-match guidance ("Keywords can include …
A platform-only query such as "TikTok" …") for any empty page, including
a page past the last result of a query that matched. With an empty query
that advice cannot help, and it reads as if nothing matched.

## What changed

`buildNoActorsFoundInstructions()`, shared by `search-actors` and
`search-actors-widget`, now gets the offset. With `offset > 0` it
returns one sentence and no keyword advice; at `offset` 0 the text is
unchanged. No new response fields; the output schema is unchanged. This
is a tool-text change to `structuredContent.instructions` and the text
content.

`search-actors` with `keywords: "", limit: 1, offset: 1000000`:

```
Before: No Actors were found for the search query "".
        Keywords can include the named platform and/or data type (e.g. "TikTok posts").
        A platform-only query such as "TikTok" is an option if more specific results do not fit.
Now:    No Actors past offset 1000000 for the search query "".
```

## Notes for reviewers (human-written)

## Proof it works

mcpc with the Claude connector tool set on this branch:

| `search-actors` call | Result |
|---|---|
| `keywords: "", limit: 1, offset: 0` | 1 Actor |
| `keywords: "", limit: 1, offset: 1000000` | `No Actors past offset
1000000 for the search query "".` |
| `keywords: "instagram scraper", limit: 5, offset: 5000` | `No Actors
past offset 5000 for the search query "instagram scraper".` |
| `keywords: "zzqqxxnotarealactorkeyword123", offset: 0` | the
three-line no-match guidance, unchanged |

The text content equals `structuredContent.instructions`, and
`structuredContent` keeps its fields (`actors: []`, `query`, `count: 0`,
`instructions`). The same `offset: 1000000` call on a build with
master's text returns the three-line guidance shown under "Before".

Unit tests (failing before the fix): an empty page at `offset` 1 returns
the new sentence in `structuredContent` and the text content, for both
`search-actors` and `search-actors-widget`. The existing
empty-first-page tests keep the three-line text.

Implemented with Claude Code: code, tests, mcpc probe and this
description. Reviewed by a separate Claude Code review pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_0149C4bPjve1UHWcxTtBsPXC

---
_Generated by [Claude
Code](https://claude.ai/code/session_0149C4bPjve1UHWcxTtBsPXC)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jirispilka

src/tools/actors/search_actors.ts

@@ -124,9 +124,11 @@ export function buildSearchActorsResult(
 
 /**
  * Builds the empty-results guidance message for when no Actors are found.
- * Interpolates the search keywords into the message.
+ * Past offset 0 the query may have matched and the page only lies past the last result, so keyword
+ * guidance does not apply (see apify/apify-mcp-server#1276).
  */
-export function buildNoActorsFoundInstructions(keywords: string): string {
+export function buildNoActorsFoundInstructions(keywords: string, offset: number): string {
+    if (offset > 0) return `No Actors past offset ${offset} for the search query "${keywords}".`;
     return dedent`
         No Actors were found for the search query "${keywords}".
         Keywords can include the named platform and/or data type (e.g. "TikTok posts").
@@ -207,7 +209,7 @@ export const searchActors: ToolEntry = Object.freeze({
         ]);
 
         if (actors.length === 0) {
-            const instructions = buildNoActorsFoundInstructions(parsed.keywords);
+            const instructions = buildNoActorsFoundInstructions(parsed.keywords, parsed.offset);
             return respondOk(instructions, {
                 structuredContent: { actors: [], query: parsed.keywords, count: 0, instructions },
             });

src/tools/widgets/search_actors_widget.ts

@@ -84,7 +84,7 @@ export const searchActorsWidget: ToolEntry = Object.freeze({
         if (actors.length === 0) {
             // Honor the widget tool's declared outputSchema: widgetActors is required, so
             // emit an empty array rather than dropping the field.
-            const instructions = buildNoActorsFoundInstructions(parsed.keywords);
+            const instructions = buildNoActorsFoundInstructions(parsed.keywords, parsed.offset);
             return respondOk(instructions, {
                 structuredContent: {
                     actors: [],

tests/unit/tools.search_actors.default.response.test.ts

@@ -187,6 +187,24 @@ describe('search-actors without widget (searchActors)', () => {
         expect(content[0].text).toBe(NO_ACTORS_FOUND_TEXT);
     });
 
+    it('says that no Actors are past the offset, without keyword guidance', async () => {
+        vi.mocked(searchAgentSafeActors).mockResolvedValue([]);
+
+        const result = await (searchActors as HelperTool).call(
+            stubToolCallContext({ keywords: SEARCH_KEYWORDS, limit: 5, offset: 1 }, mockApifyClient(), {
+                loadedToolNames: [],
+            }),
+        );
+
+        const { structuredContent, content } = result as {
+            structuredContent: Record<string, unknown>;
+            content: { type: string; text: string }[];
+        };
+        const text = `No Actors past offset 1 for the search query "${SEARCH_KEYWORDS}".`;
+        expect(structuredContent).toEqual({ actors: [], query: SEARCH_KEYWORDS, count: 0, instructions: text });
+        expect(content).toEqual([{ type: 'text', text }]);
+    });
+
     it('declares every field the structured card emits (guards schema/runtime drift)', () => {
         // Regression guard for #889: the advertised output schema must declare every field
         // the runtime card actually emits. `pictureUrl` was emitted but undeclared — this

tests/unit/tools.search_actors.widget.response.test.ts

@@ -115,6 +115,27 @@ describe('search-actors-widget response', () => {
         expect(_meta).toBeUndefined();
     });
 
+    it('says that no Actors are past the offset, without keyword guidance', async () => {
+        vi.mocked(searchAgentSafeActors).mockResolvedValue([]);
+
+        const result = await (searchActorsWidget as HelperTool).call(
+            stubToolCallContext({ keywords: SEARCH_KEYWORDS, limit: 5, offset: 1 }, mockApifyClient(), {
+                loadedToolNames: [],
+            }),
+        );
+
+        const { structuredContent, content, _meta } = result as {
+            structuredContent: Record<string, unknown>;
+            content: { type: string; text: string }[];
+            _meta?: unknown;
+        };
+        expect(structuredContent).toEqual({ actors: [], query: SEARCH_KEYWORDS, count: 0, widgetActors: [] });
+        expect(content).toEqual([
+            { type: 'text', text: `No Actors past offset 1 for the search query "${SEARCH_KEYWORDS}".` },
+        ]);
+        expect(_meta).toBeUndefined();
+    });
+
     it('appends the not-runnable caveat when call-actor is absent', async () => {
         vi.mocked(searchAgentSafeActors).mockResolvedValue([MOCK_STORE_ACTOR]);