feat: improve tool descriptions with pagination guidance and MCP annotations

src/tools/images/index.ts

@@ -10,11 +10,20 @@ export const name = 'brave_image_search';
 
 export const annotations: ToolAnnotations = {
   title: 'Brave Image Search',
+  readOnlyHint: true, // Only reads data via external API, no modifications
+  idempotentHint: true, // Same query = same API operation, repeatable without side effects
   openWorldHint: true,
 };
 
 export const description = `
     Performs an image search using the Brave Search API. Helpful for when you need pictures of people, places, things, graphic design ideas, art inspiration, and more. When relaying results in a markdown environment, it may be helpful to include images in the results (e.g., ![image.title](image.properties.url)).
+
+    Context Control Tips:
+        - Start with count=10-20 for initial image searches to minimize context usage
+        - Default count=50 provides comprehensive results but uses more context
+        - Maximum count=200 available for exhaustive searches when needed
+        - Note: No pagination available for images (no offset parameter)
+        - Returns URLs only (no base64 data) for efficient context usage since v2.0
 `;
 
 export const execute = async (params: QueryParams) => {

src/tools/images/schemas/input.ts

@@ -30,7 +30,7 @@ export const params = z.object({
     .max(200)
     .default(50)
     .describe(
-      'Number of results (1-200, default 50). Combine this parameter with `offset` to paginate search results.'
+      'Number of results (1-200, default 50). For optimal context usage, start with 10-20 results and request more if needed.'
     )
     .optional(),
   safesearch: z

src/tools/local/index.ts

@@ -16,18 +16,27 @@ export const name = 'brave_local_search';
 
 export const annotations: ToolAnnotations = {
   title: 'Brave Local Search',
+  readOnlyHint: true, // Only reads data via external API, no modifications
+  idempotentHint: true, // Same query = same API operation, repeatable without side effects
   openWorldHint: true,
 };
 
 export const description = `
     Brave Local Search API provides enrichments for location search results. Access to this API is available only through the Brave Search API Pro plans; confirm the user's plan before using this tool (if the user does not have a Pro plan, use the brave_web_search tool). Searches for local businesses and places using Brave's Local Search API. Best for queries related to physical locations, businesses, restaurants, services, etc.
-    
+
     Returns detailed information including:
         - Business names and addresses
         - Ratings and review counts
         - Phone numbers and opening hours
 
     Use this when the query implies 'near me', 'in my area', or mentions specific locations (e.g., 'in San Francisco'). This tool automatically falls back to brave_web_search if no local results are found.
+
+    Context Control Tips:
+        - Start with count=5 for initial local searches to get top-rated businesses efficiently
+        - Location results include rich metadata (ratings, hours, descriptions) - use smaller counts
+        - Processes up to 20 location IDs per request (API limit)
+        - Pagination available via offset (0-9) for browsing more local results
+        - Falls back to web search automatically if no locations found (Pro plan required)
 `;
 
 // Access to Local API is available through the Pro plans.

src/tools/news/index.ts

@@ -8,26 +8,35 @@ export const name = 'brave_news_search';
 
 export const annotations: ToolAnnotations = {
   title: 'Brave News Search',
+  readOnlyHint: true, // Only reads data via external API, no modifications
+  idempotentHint: true, // Same query = same API operation, repeatable without side effects
   openWorldHint: true,
 };
 
 export const description = `
     This tool searches for news articles using Brave's News Search API based on the user's query. Use it when you need current news information, breaking news updates, or articles about specific topics, events, or entities.
-    
+
     When to use:
         - Finding recent news articles on specific topics
         - Getting breaking news updates
         - Researching current events or trending stories
         - Gathering news sources and headlines for analysis
 
     Returns a JSON list of news-related results with title, url, and description. Some results may contain snippets of text from the article.
-    
+
     When relaying results in markdown-supporting environments, always cite sources with hyperlinks.
-    
+
     Examples:
         - "According to [Reuters](https://www.reuters.com/technology/china-bans/), China bans uncertified and recalled power banks on planes".
         - "The [New York Times](https://www.nytimes.com/2025/06/27/us/technology/ev-sales.html) reports that Tesla's EV sales have increased by 20%".
         - "According to [BBC News](https://www.bbc.com/news/world-europe-65910000), the UK government has announced a new policy to support renewable energy".
+
+    Context Control Tips:
+        - Start with count=5-10 for breaking news queries to get latest headlines efficiently
+        - Use count=20 (default) for comprehensive news coverage
+        - For more articles, use offset parameter (e.g., offset=5) to paginate through results
+        - Maximum pagination: offset can only go up to 9, limiting total to ~59 articles (count=50, offset=9)
+        - Set freshness='pd' for last 24 hours to reduce result volume and improve relevance
 `;
 
 export const execute = async (params: QueryParams) => {

src/tools/news/params.ts

@@ -33,15 +33,19 @@ export const params = z.object({
     .min(1)
     .max(50)
     .default(20)
-    .describe('Number of results (1-50, default 20)')
+    .describe(
+      'Number of results (1-50, default 20). Start with 5-10 for breaking news, use 20 for comprehensive coverage.'
+    )
     .optional(),
   offset: z
     .number()
     .int()
     .min(0)
     .max(9)
     .default(0)
-    .describe('Pagination offset (max 9, default 0)')
+    .describe(
+      'Pagination offset (0-9, default 0). Use to get more articles: offset=20 gets articles 21-40 (when count=20).'
+    )
     .optional(),
   spellcheck: z
     .boolean()

src/tools/summarizer/index.ts

@@ -8,6 +8,8 @@ export const name = 'brave_summarizer';
 
 export const annotations: ToolAnnotations = {
   title: 'Brave Summarizer',
+  readOnlyHint: true, // Only reads data via external API, no modifications
+  idempotentHint: true, // Same query = same API operation, repeatable without side effects
   openWorldHint: true,
 };
 
@@ -24,6 +26,13 @@ export const description = `
     Returns a text summary that consolidates information from the search results. Optional features include inline references to source URLs and additional entity information.
 
     Requirements: Must first perform a web search using brave_web_search with summary=true parameter. Requires a Pro AI subscription to access the summarizer functionality.
+
+    Context Control Tips:
+        - This tool provides the MOST context-efficient way to get comprehensive information
+        - Returns a single concise summary instead of multiple search results
+        - Ideal when you need an overview before diving into specific results
+        - Use web search with smaller count (5-10) + summarizer for optimal context usage
+        - No pagination needed - summarizer processes all search results at once
 `;
 
 export const execute = async (params: SummarizerQueryParams) => {

src/tools/videos/index.ts

@@ -8,6 +8,8 @@ export const name = 'brave_video_search';
 
 export const annotations: ToolAnnotations = {
   title: 'Brave Video Search',
+  readOnlyHint: true, // Only reads data via external API, no modifications
+  idempotentHint: true, // Same query = same API operation, repeatable without side effects
   openWorldHint: true,
 };
 
@@ -19,6 +21,13 @@ export const description = `
         - Useful for discovering video content, getting video metadata, or finding videos from specific creators/publishers.
 
     Returns a JSON list of video-related results with title, url, description, duration, and thumbnail_url.
+
+    Context Control Tips:
+        - Start with count=5-10 for initial video discovery to minimize context usage
+        - Use count=20 (default) for balanced video results
+        - Combine count with offset to paginate (e.g., count=10, offset=10 for next page)
+        - Maximum pagination: offset can only go up to 9, limiting total to ~59 videos (count=50, offset=9)
+        - Video metadata is compact, so slightly higher counts (15-20) are context-efficient
 `;
 
 export const execute = async (params: QueryParams) => {

src/tools/videos/params.ts

@@ -37,7 +37,7 @@ export const params = z.object({
     .max(50)
     .default(20)
     .describe(
-      'Number of results (1-50, default 20). Combine this parameter with `offset` to paginate search results.'
+      'Number of results (1-50, default 20). Start with 5-10 for initial discovery, use 20 for balanced results. Combine with offset for pagination.'
     )
     .optional(),
   offset: z
@@ -47,7 +47,7 @@ export const params = z.object({
     .max(9)
     .default(0)
     .describe(
-      'Pagination offset (max 9, default 0). Combine this parameter with `count` to paginate search results.'
+      'Pagination offset (0-9, default 0). Example: offset=10 with count=10 gets videos 11-20. Maximum offset is 9.'
     )
     .optional(),
   spellcheck: z

src/tools/web/index.ts

@@ -20,6 +20,8 @@ export const name = 'brave_web_search';
 
 export const annotations: ToolAnnotations = {
   title: 'Brave Web Search',
+  readOnlyHint: true, // Only reads data via external API, no modifications
+  idempotentHint: true, // Same query = same API operation, repeatable without side effects
   openWorldHint: true,
 };
 
@@ -34,8 +36,15 @@ export const description = `
         - Research requiring diverse result types (web pages, images, reviews, etc.)
 
     Returns a JSON list of web results with title, description, and URL.
-    
+
     When the "results_filter" parameter is empty, JSON results may also contain FAQ, Discussions, News, and Video results.
+
+    Context Control Tips:
+        - Start with count=5 for initial queries to minimize context usage
+        - Use count=10 (default) for balanced information vs. context efficiency
+        - For follow-up searches, use offset parameter (e.g., offset=10) to paginate through results
+        - Maximum pagination: offset can only go up to 9, limiting total accessible results to ~29 (count=20, offset=9)
+        - Consider using result_filter to limit result types and reduce context usage
 `;
 
 export const execute = async (params: QueryParams) => {

src/tools/web/params.ts

@@ -162,7 +162,7 @@ export const params = z.object({
     .max(20)
     .default(10)
     .describe(
-      'Number of results (1-20, default 10). Applies only to web search results (i.e., has no effect on locations, news, videos, etc.)'
+      'Number of results (1-20, default 10). Start with 5 for context efficiency, use 10-15 for comprehensive results. Applies only to web search results (i.e., has no effect on locations, news, videos, etc.)'
     )
     .optional(),
   offset: z
@@ -171,7 +171,9 @@ export const params = z.object({
     .min(0)
     .max(9)
     .default(0)
-    .describe('Pagination offset (max 9, default 0)')
+    .describe(
+      'Pagination offset (0-9, default 0). Use to get additional results: offset=10 gets results 11-20 (when count=10). Max offset is 9.'
+    )
     .optional(),
   safesearch: z
     .enum(['off', 'moderate', 'strict'])