[DOCS] Grep content mode does not document pagination and past-end results

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

The “Grep tool behavior” section, especially the content output mode and the head_limit/offset pagination parameters.

Current Documentation

The section currently says:

The Grep tool searches file contents for patterns. Where Glob finds files by name, Grep finds lines inside them. Three output modes control what comes back: files_with_matches: file paths only, no line content. This is the default. content: matching lines with file and line number. * count: match count per file, followed by a total across all matching files. The total covers every match even when the tool's head_limit or offset parameters truncate the listed per-file entries.

What's Wrong or Missing?

The documentation explains that head_limit and offset can truncate count output, but it does not explain how to paginate content results or how to interpret a page after the final match. It does not distinguish “there are no more results at this offset” from “the pattern has no matches.”

Claude Code v2.1.210 fixed Grep content mode incorrectly claiming “No matches found” when pagination moved past the end of the results. Users reading the current documentation have no guidance for detecting the end of a paginated content result set or for understanding the corrected empty-page behavior.

Suggested Improvement

Expand the content mode documentation to describe head_limit and offset pagination, including:

1. Which unit offset advances through when content mode is used.
2. How to request the next page after applying head_limit.
3. That an offset beyond the final matching entry means pagination is exhausted, not that the pattern was absent from the searched files.
4. The expected empty-result response for a past-the-end page, with a small example.

Add the same pagination and past-end semantics to the Grep input reference in the Agent SDK documentation so SDK users can implement result paging consistently.

Impact

Medium - Makes feature difficult to understand

Additional Context

The behavior change is recorded in the v2.1.210 release notes: https://code.claude.com/docs/en/changelog

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference | “Grep tool behavior” output modes and pagination semantics |
| https://code.claude.com/docs/en/agent-sdk/typescript | GrepInput head_limit and offset fields |

Total scope: 2 pages affected