diff --git a/README.md b/README.md
index 57976cb..b91edef 100644
--- a/README.md
+++ b/README.md
@@ -200,6 +200,8 @@ Languages: `en` (default), `es`, `ja`, `pt` (Brazilian Portuguese), `zh` (Simpli
 
 Use `heading`, `query`, or a page URL's `#anchor` for focused reading, in that precedence order. Missing heading anchors return an error with actual headings; an empty fragment means the whole page. Content arrives in 50 KiB windows, with up to five matching sections per group.
 
+Start with a small search limit and widen it when needed. Use a known heading or anchor; otherwise try a focused query. Read a short page in full when its whole subject is relevant.
+
 Full URLs must match the configured origin and base path. Foreign authorities, query strings, protocol-relative URLs and enterprise/version paths are rejected rather than reinterpreted as current GitHub.com docs. Search breadcrumbs provide context, not executable heading names; hits absent from the catalogue carry an availability notice.
 
 Follow the returned cursor-only call to continue `get_doc` or `list_docs`. Cursors work across restarts when content is unchanged; changed content returns a restart call. Legacy `offset` calls still work but cannot detect changed content. Cursors from earlier releases must be restarted.
diff --git a/internal/mcpserver/tools.go b/internal/mcpserver/tools.go
index 21063fc..8c734fe 100644
--- a/internal/mcpserver/tools.go
+++ b/internal/mcpserver/tools.go
@@ -50,7 +50,7 @@ type (
 		Cursor  string `json:"cursor,omitempty" jsonschema:"Opaque continuation from a previous get_doc result; pass cursor only"`
 		Slug    string `json:"slug,omitempty"              jsonschema:"Doc slug from list_docs or search_docs, e.g. \"en/actions/tutorials/build-and-test-code/nodejs\". A full docs URL or an absolute path also works."`
 		Heading string `json:"heading,omitempty" jsonschema:"Optional heading, matched by exact text or its #kebab-anchor; returns only that section. A miss lists the page's real headings."`
-		Query   string `json:"query,omitempty"   jsonschema:"Optional keywords; returns only the sections of the page matching them, verbatim with heading breadcrumbs; the cheapest way to pull one fact from a long page. Ignored when heading is set."`
+		Query   string `json:"query,omitempty"   jsonschema:"Optional keywords for focused lookup when the heading is unknown; returns matching sections verbatim with breadcrumbs. Broad queries may return more text than the full page. Ignored when heading is set."`
 		Offset  int    `json:"offset,omitempty"  jsonschema:"Legacy byte offset; cannot validate snapshots. Prefer cursor continuations."`
 	}
 )
@@ -78,13 +78,13 @@ func (s *Server) registerTools() {
 
 	mcp.AddTool(s.mcp, &mcp.Tool{
 		Name:        toolSearchDocs,
-		Description: "Bounded ranked search using GitHub’s upstream index, with reduced coverage over catalogue metadata and cached bodies during outages. Returns ranked slugs with contextual breadcrumbs, not executable heading names. Follow up with get_doc(slug) or get_doc(slug, query=...). Hits missing from the catalogue carry an availability notice.",
+		Description: "Bounded ranked search using GitHub’s upstream index, with reduced coverage over catalogue metadata and cached bodies during outages. Start with a small limit and widen when evidence is missing. Returns ranked slugs with contextual breadcrumbs, not executable heading names. Follow up with get_doc(slug) or get_doc(slug, query=...). Hits missing from the catalogue carry an availability notice.",
 		Annotations: readOnly("Search documentation"),
 	}, s.handleSearchDocs)
 
 	mcp.AddTool(s.mcp, &mcp.Tool{
 		Name:        toolGetDoc,
-		Description: "Fetch one GitHub documentation page as markdown. Accepts a page slug or a URL on the configured docs origin, optionally with #anchor. Selection precedence is heading, query, fragment, then full page. A fragment requires a page path; missing heading anchors return an error. Query strings, foreign origins and enterprise/version paths are rejected. Returns page content and source freshness. Use query= for focused lookup, heading= for a named section. Initial calls require slug; follow cursor-only continuations for every matching section and byte window.",
+		Description: "Fetch one GitHub documentation page as markdown. Accepts a page slug or a URL on the configured docs origin, optionally with #anchor. Selection precedence is heading, query, fragment, then full page. A fragment requires a page path; missing heading anchors return an error. Query strings, foreign origins and enterprise/version paths are rejected. Returns page content and source freshness. Use a known heading or anchor; otherwise try a focused query. Read a short page in full when its whole subject is relevant. Initial calls require slug; follow cursor-only continuations for every matching section and byte window.",
 		Annotations: readOnly("Get documentation page"),
 	}, s.handleGetDoc)
 }