@upstash/context7-tools-ai-sdk 0.2.0-canary-20251209084107 → 0.2.0

package/dist/agent.cjs

@@ -27,7 +27,7 @@ module.exports = __toCommonJS(agents_exports);
 // src/agents/context7.ts
 var import_ai3 = require("ai");
 
-// src/tools/resolve-library.ts
+// src/tools/resolve-library-id.ts
 var import_ai = require("ai");
 var import_zod = require("zod");
 var import_context7_sdk = require("@upstash/context7-sdk");
@@ -37,12 +37,12 @@ var AGENT_PROMPT = `You are a documentation search assistant powered by Context7
 
 CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:
 
-Step 1: ALWAYS start by calling 'resolveLibrary' with the library name from the user's query
+Step 1: ALWAYS start by calling 'resolveLibraryId' with the library name from the user's query
    - Extract the main library/framework name (e.g., "React", "Next.js", "Vue")
-   - Call resolveLibrary with just the library name
+   - Call resolveLibraryId with just the library name
    - Review ALL the search results returned
 
-Step 2: Analyze the results from resolveLibrary and select the BEST library ID based on:
+Step 2: Analyze the results from resolveLibraryId and select the BEST library ID based on:
    - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)
    - Name similarity to what the user is looking for
    - Description relevance
@@ -50,24 +50,20 @@ Step 2: Analyze the results from resolveLibrary and select the BEST library ID b
    - Code snippet coverage (higher is better)
    - Benchmark score (higher is better)
 
-Step 3: Call 'getLibraryDocs' with the selected library ID
-   - Use the exact library ID from the resolveLibrary results
-   - ALWAYS extract and include a relevant topic from the user's query (e.g., "Server-Side Rendering", "routing", "authentication")
-   - Start with page=1 (default)
+Step 3: Call 'queryDocs' with the selected library ID and the user's query
+   - Use the exact library ID from the resolveLibraryId results
+   - Include the user's original question as the query parameter
 
-Step 4: If the documentation from page 1 isn't sufficient, call 'getLibraryDocs' again with page=2
-   - Use the same library ID and the SAME topic from step 3
-   - This gives you more comprehensive documentation
-
-Step 5: Provide a clear answer with code examples from the documentation
+Step 4: Provide a clear answer with code examples from the documentation
 
 IMPORTANT:
-- You MUST call resolveLibrary first before calling getLibraryDocs
-- Do NOT skip resolveLibrary - it helps you find the correct official documentation
+- You MUST call resolveLibraryId first before calling queryDocs
+- Do NOT skip resolveLibraryId - it helps you find the correct official documentation
+- Do not call either tool more than 3 times per question
 - Always cite which library ID you used`;
-var RESOLVE_LIBRARY_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.
+var RESOLVE_LIBRARY_ID_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
 
-You MUST call this function before 'getLibraryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
+You MUST call this function before 'queryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
 
 Selection Process:
 1. Analyze the query to understand what library/package the user is looking for
@@ -84,100 +80,71 @@ Response Format:
 - If multiple good matches exist, acknowledge this but proceed with the most relevant one
 - If no good matches exist, clearly state this and suggest query refinements
 
-For ambiguous queries, request clarification before proceeding with a best-guess match.`;
-var GET_LIBRARY_DOCS_DESCRIPTION = "Fetches up-to-date documentation for a library. You must call 'resolveLibrary' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. Use mode='code' (default) for API references and code examples, or mode='info' for conceptual guides, narrative information, and architectural questions.";
+For ambiguous queries, request clarification before proceeding with a best-guess match.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`;
+var QUERY_DOCS_DESCRIPTION = `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.
+
+You must call 'resolveLibraryId' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`;
 
-// src/tools/resolve-library.ts
-function resolveLibrary(config = {}) {
+// src/tools/resolve-library-id.ts
+function resolveLibraryId(config = {}) {
   const { apiKey } = config;
   const getClient = () => new import_context7_sdk.Context7({ apiKey });
   return (0, import_ai.tool)({
-    description: RESOLVE_LIBRARY_DESCRIPTION,
+    description: RESOLVE_LIBRARY_ID_DESCRIPTION,
     inputSchema: import_zod.z.object({
+      query: import_zod.z.string().describe(
+        "The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
+      ),
       libraryName: import_zod.z.string().describe("Library name to search for and retrieve a Context7-compatible library ID.")
     }),
-    execute: async ({ libraryName }) => {
+    execute: async ({ query, libraryName }) => {
       try {
         const client = getClient();
-        const response = await client.searchLibrary(libraryName);
-        if (!response.results || response.results.length === 0) {
-          return {
-            success: false,
-            error: "No libraries found matching your query.",
-            suggestions: "Try a different search term or check the library name."
-          };
+        const results = await client.searchLibrary(query, libraryName, { type: "txt" });
+        if (!results || results.length === 0) {
+          return `No libraries found matching "${libraryName}". Try a different search term or check the library name.`;
         }
-        return {
-          success: true,
-          results: response.results,
-          totalResults: response.results.length
-        };
+        return results;
       } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : "Failed to search libraries",
-          suggestions: "Check your API key and try again, or try a different search term."
-        };
+        const errorMessage = error instanceof Error ? error.message : "Failed to search libraries";
+        return `Error searching for libraries: ${errorMessage}. Check your API key and try again.`;
       }
     }
   });
 }
 
-// src/tools/get-library-docs.ts
+// src/tools/query-docs.ts
 var import_ai2 = require("ai");
 var import_zod2 = require("zod");
 var import_context7_sdk2 = require("@upstash/context7-sdk");
-function getLibraryDocs(config = {}) {
-  const { apiKey, defaultMaxResults = 10 } = config;
+function queryDocs(config = {}) {
+  const { apiKey } = config;
   const getClient = () => new import_context7_sdk2.Context7({ apiKey });
   return (0, import_ai2.tool)({
-    description: GET_LIBRARY_DOCS_DESCRIPTION,
+    description: QUERY_DOCS_DESCRIPTION,
     inputSchema: import_zod2.z.object({
       libraryId: import_zod2.z.string().describe(
-        "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibrary' or directly from user query in the format '/org/project' or '/org/project/version'."
+        "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibraryId' or directly from user query in the format '/org/project' or '/org/project/version'."
       ),
-      mode: import_zod2.z.enum(["code", "info"]).optional().default("code").describe(
-        "Documentation mode: 'code' for API references and code examples (default), 'info' for conceptual guides, narrative information, and architectural questions."
-      ),
-      topic: import_zod2.z.string().optional().describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
-      page: import_zod2.z.number().int().min(1).max(10).optional().describe(
-        "Page number for pagination (start: 1, default: 1). If the context is not sufficient, try page=2, page=3, page=4, etc. with the same topic."
+      query: import_zod2.z.string().describe(
+        "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
       )
     }),
-    execute: async ({
-      libraryId,
-      mode = "code",
-      topic,
-      page = 1
-    }) => {
+    execute: async ({ libraryId, query }) => {
       try {
         const client = getClient();
-        const baseOptions = {
-          page,
-          limit: defaultMaxResults,
-          topic: topic?.trim() || void 0
-        };
-        const response = mode === "info" ? await client.getDocs(libraryId, { ...baseOptions, mode: "info" }) : await client.getDocs(libraryId, { ...baseOptions, mode: "code" });
-        if (!response.snippets?.length) {
-          return {
-            success: false,
-            error: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolveLibrary' with the package name you wish to retrieve documentation for.",
-            libraryId
-          };
+        const documentation = await client.getContext(query, libraryId, { type: "txt" });
+        if (!documentation || documentation.length === 0) {
+          return `No documentation found for library "${libraryId}". This might have happened because you used an invalid Context7-compatible library ID. Use 'resolveLibraryId' to get a valid ID.`;
         }
-        return {
-          success: true,
-          libraryId,
-          snippets: response.snippets,
-          pagination: response.pagination,
-          totalTokens: response.totalTokens
-        };
+        return documentation;
       } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : "Failed to fetch documentation",
-          libraryId
-        };
+        const errorMessage = error instanceof Error ? error.message : "Failed to fetch documentation";
+        return `Error fetching documentation for "${libraryId}": ${errorMessage}`;
       }
     }
   });
@@ -186,24 +153,16 @@ function getLibraryDocs(config = {}) {
 // src/agents/context7.ts
 var Context7Agent = class extends import_ai3.Experimental_Agent {
   constructor(config) {
-    const {
-      model,
-      stopWhen = (0, import_ai3.stepCountIs)(5),
-      system,
-      apiKey,
-      defaultMaxResults,
-      tools,
-      ...agentSettings
-    } = config;
-    const context7Config = { apiKey, defaultMaxResults };
+    const { model, stopWhen = (0, import_ai3.stepCountIs)(5), system, apiKey, tools, ...agentSettings } = config;
+    const context7Config = { apiKey };
     super({
       ...agentSettings,
       model,
       system: system || AGENT_PROMPT,
       tools: {
         ...tools,
-        resolveLibrary: resolveLibrary(context7Config),
-        getLibraryDocs: getLibraryDocs(context7Config)
+        resolveLibraryId: resolveLibraryId(context7Config),
+        queryDocs: queryDocs(context7Config)
       },
       stopWhen
     });

package/dist/agent.d.cts

@@ -8,11 +8,6 @@ interface Context7AgentConfig extends Experimental_AgentSettings<ToolSet> {
      * Context7 API key. If not provided, uses the CONTEXT7_API_KEY environment variable.
      */
     apiKey?: string;
-    /**
-     * Default maximum number of documentation results per request.
-     * @default 10
-     */
-    defaultMaxResults?: number;
 }
 /**
  * Context7 documentation search agent

package/dist/agent.d.ts

@@ -8,11 +8,6 @@ interface Context7AgentConfig extends Experimental_AgentSettings<ToolSet> {
      * Context7 API key. If not provided, uses the CONTEXT7_API_KEY environment variable.
      */
     apiKey?: string;
-    /**
-     * Default maximum number of documentation results per request.
-     * @default 10
-     */
-    defaultMaxResults?: number;
 }
 /**
  * Context7 documentation search agent

package/dist/agent.js

@@ -1,6 +1,6 @@
 import {
   Context7Agent
-} from "./chunk-AMSBQOUU.js";
+} from "./chunk-5OOZPW2Y.js";
 export {
   Context7Agent
 };

package/dist/chunk-5OOZPW2Y.js

@@ -0,0 +1,165 @@
+// src/agents/context7.ts
+import {
+  Experimental_Agent as Agent,
+  stepCountIs
+} from "ai";
+
+// src/tools/resolve-library-id.ts
+import { tool } from "ai";
+import { z } from "zod";
+import { Context7 } from "@upstash/context7-sdk";
+
+// src/prompts/system.ts
+var SYSTEM_PROMPT = `You are a documentation search assistant powered by Context7.
+
+Your role is to help users find accurate, up-to-date documentation for libraries and frameworks.
+
+When answering questions:
+1. Search for the relevant library documentation
+2. Provide code examples when available
+3. Cite your sources by mentioning the library ID used`;
+var AGENT_PROMPT = `You are a documentation search assistant powered by Context7.
+
+CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:
+
+Step 1: ALWAYS start by calling 'resolveLibraryId' with the library name from the user's query
+   - Extract the main library/framework name (e.g., "React", "Next.js", "Vue")
+   - Call resolveLibraryId with just the library name
+   - Review ALL the search results returned
+
+Step 2: Analyze the results from resolveLibraryId and select the BEST library ID based on:
+   - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)
+   - Name similarity to what the user is looking for
+   - Description relevance
+   - Source reputation (High/Medium is better)
+   - Code snippet coverage (higher is better)
+   - Benchmark score (higher is better)
+
+Step 3: Call 'queryDocs' with the selected library ID and the user's query
+   - Use the exact library ID from the resolveLibraryId results
+   - Include the user's original question as the query parameter
+
+Step 4: Provide a clear answer with code examples from the documentation
+
+IMPORTANT:
+- You MUST call resolveLibraryId first before calling queryDocs
+- Do NOT skip resolveLibraryId - it helps you find the correct official documentation
+- Do not call either tool more than 3 times per question
+- Always cite which library ID you used`;
+var RESOLVE_LIBRARY_ID_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
+
+You MUST call this function before 'queryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
+
+Selection Process:
+1. Analyze the query to understand what library/package the user is looking for
+2. Return the most relevant match based on:
+- Name similarity to the query (exact matches prioritized)
+- Description relevance to the query's intent
+- Documentation coverage (prioritize libraries with higher Code Snippet counts)
+- Source reputation (consider libraries with High or Medium reputation more authoritative)
+- Benchmark Score: Quality indicator (100 is the highest score)
+
+Response Format:
+- Return the selected library ID in a clearly marked section
+- Provide a brief explanation for why this library was chosen
+- If multiple good matches exist, acknowledge this but proceed with the most relevant one
+- If no good matches exist, clearly state this and suggest query refinements
+
+For ambiguous queries, request clarification before proceeding with a best-guess match.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`;
+var QUERY_DOCS_DESCRIPTION = `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.
+
+You must call 'resolveLibraryId' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`;
+
+// src/tools/resolve-library-id.ts
+function resolveLibraryId(config = {}) {
+  const { apiKey } = config;
+  const getClient = () => new Context7({ apiKey });
+  return tool({
+    description: RESOLVE_LIBRARY_ID_DESCRIPTION,
+    inputSchema: z.object({
+      query: z.string().describe(
+        "The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
+      ),
+      libraryName: z.string().describe("Library name to search for and retrieve a Context7-compatible library ID.")
+    }),
+    execute: async ({ query, libraryName }) => {
+      try {
+        const client = getClient();
+        const results = await client.searchLibrary(query, libraryName, { type: "txt" });
+        if (!results || results.length === 0) {
+          return `No libraries found matching "${libraryName}". Try a different search term or check the library name.`;
+        }
+        return results;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Failed to search libraries";
+        return `Error searching for libraries: ${errorMessage}. Check your API key and try again.`;
+      }
+    }
+  });
+}
+
+// src/tools/query-docs.ts
+import { tool as tool2 } from "ai";
+import { z as z2 } from "zod";
+import { Context7 as Context72 } from "@upstash/context7-sdk";
+function queryDocs(config = {}) {
+  const { apiKey } = config;
+  const getClient = () => new Context72({ apiKey });
+  return tool2({
+    description: QUERY_DOCS_DESCRIPTION,
+    inputSchema: z2.object({
+      libraryId: z2.string().describe(
+        "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibraryId' or directly from user query in the format '/org/project' or '/org/project/version'."
+      ),
+      query: z2.string().describe(
+        "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
+      )
+    }),
+    execute: async ({ libraryId, query }) => {
+      try {
+        const client = getClient();
+        const documentation = await client.getContext(query, libraryId, { type: "txt" });
+        if (!documentation || documentation.length === 0) {
+          return `No documentation found for library "${libraryId}". This might have happened because you used an invalid Context7-compatible library ID. Use 'resolveLibraryId' to get a valid ID.`;
+        }
+        return documentation;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Failed to fetch documentation";
+        return `Error fetching documentation for "${libraryId}": ${errorMessage}`;
+      }
+    }
+  });
+}
+
+// src/agents/context7.ts
+var Context7Agent = class extends Agent {
+  constructor(config) {
+    const { model, stopWhen = stepCountIs(5), system, apiKey, tools, ...agentSettings } = config;
+    const context7Config = { apiKey };
+    super({
+      ...agentSettings,
+      model,
+      system: system || AGENT_PROMPT,
+      tools: {
+        ...tools,
+        resolveLibraryId: resolveLibraryId(context7Config),
+        queryDocs: queryDocs(context7Config)
+      },
+      stopWhen
+    });
+  }
+};
+
+export {
+  SYSTEM_PROMPT,
+  AGENT_PROMPT,
+  RESOLVE_LIBRARY_ID_DESCRIPTION,
+  QUERY_DOCS_DESCRIPTION,
+  resolveLibraryId,
+  queryDocs,
+  Context7Agent
+};

package/dist/index.cjs

@@ -22,18 +22,18 @@ var src_exports = {};
 __export(src_exports, {
   AGENT_PROMPT: () => AGENT_PROMPT,
   Context7Agent: () => Context7Agent,
-  GET_LIBRARY_DOCS_DESCRIPTION: () => GET_LIBRARY_DOCS_DESCRIPTION,
-  RESOLVE_LIBRARY_DESCRIPTION: () => RESOLVE_LIBRARY_DESCRIPTION,
+  QUERY_DOCS_DESCRIPTION: () => QUERY_DOCS_DESCRIPTION,
+  RESOLVE_LIBRARY_ID_DESCRIPTION: () => RESOLVE_LIBRARY_ID_DESCRIPTION,
   SYSTEM_PROMPT: () => SYSTEM_PROMPT,
-  getLibraryDocs: () => getLibraryDocs,
-  resolveLibrary: () => resolveLibrary
+  queryDocs: () => queryDocs,
+  resolveLibraryId: () => resolveLibraryId
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/agents/context7.ts
 var import_ai3 = require("ai");
 
-// src/tools/resolve-library.ts
+// src/tools/resolve-library-id.ts
 var import_ai = require("ai");
 var import_zod = require("zod");
 var import_context7_sdk = require("@upstash/context7-sdk");
@@ -51,12 +51,12 @@ var AGENT_PROMPT = `You are a documentation search assistant powered by Context7
 
 CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:
 
-Step 1: ALWAYS start by calling 'resolveLibrary' with the library name from the user's query
+Step 1: ALWAYS start by calling 'resolveLibraryId' with the library name from the user's query
    - Extract the main library/framework name (e.g., "React", "Next.js", "Vue")
-   - Call resolveLibrary with just the library name
+   - Call resolveLibraryId with just the library name
    - Review ALL the search results returned
 
-Step 2: Analyze the results from resolveLibrary and select the BEST library ID based on:
+Step 2: Analyze the results from resolveLibraryId and select the BEST library ID based on:
    - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)
    - Name similarity to what the user is looking for
    - Description relevance
@@ -64,24 +64,20 @@ Step 2: Analyze the results from resolveLibrary and select the BEST library ID b
    - Code snippet coverage (higher is better)
    - Benchmark score (higher is better)
 
-Step 3: Call 'getLibraryDocs' with the selected library ID
-   - Use the exact library ID from the resolveLibrary results
-   - ALWAYS extract and include a relevant topic from the user's query (e.g., "Server-Side Rendering", "routing", "authentication")
-   - Start with page=1 (default)
+Step 3: Call 'queryDocs' with the selected library ID and the user's query
+   - Use the exact library ID from the resolveLibraryId results
+   - Include the user's original question as the query parameter
 
-Step 4: If the documentation from page 1 isn't sufficient, call 'getLibraryDocs' again with page=2
-   - Use the same library ID and the SAME topic from step 3
-   - This gives you more comprehensive documentation
-
-Step 5: Provide a clear answer with code examples from the documentation
+Step 4: Provide a clear answer with code examples from the documentation
 
 IMPORTANT:
-- You MUST call resolveLibrary first before calling getLibraryDocs
-- Do NOT skip resolveLibrary - it helps you find the correct official documentation
+- You MUST call resolveLibraryId first before calling queryDocs
+- Do NOT skip resolveLibraryId - it helps you find the correct official documentation
+- Do not call either tool more than 3 times per question
 - Always cite which library ID you used`;
-var RESOLVE_LIBRARY_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.
+var RESOLVE_LIBRARY_ID_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
 
-You MUST call this function before 'getLibraryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
+You MUST call this function before 'queryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
 
 Selection Process:
 1. Analyze the query to understand what library/package the user is looking for
@@ -98,100 +94,71 @@ Response Format:
 - If multiple good matches exist, acknowledge this but proceed with the most relevant one
 - If no good matches exist, clearly state this and suggest query refinements
 
-For ambiguous queries, request clarification before proceeding with a best-guess match.`;
-var GET_LIBRARY_DOCS_DESCRIPTION = "Fetches up-to-date documentation for a library. You must call 'resolveLibrary' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. Use mode='code' (default) for API references and code examples, or mode='info' for conceptual guides, narrative information, and architectural questions.";
+For ambiguous queries, request clarification before proceeding with a best-guess match.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`;
+var QUERY_DOCS_DESCRIPTION = `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.
+
+You must call 'resolveLibraryId' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`;
 
-// src/tools/resolve-library.ts
-function resolveLibrary(config = {}) {
+// src/tools/resolve-library-id.ts
+function resolveLibraryId(config = {}) {
   const { apiKey } = config;
   const getClient = () => new import_context7_sdk.Context7({ apiKey });
   return (0, import_ai.tool)({
-    description: RESOLVE_LIBRARY_DESCRIPTION,
+    description: RESOLVE_LIBRARY_ID_DESCRIPTION,
     inputSchema: import_zod.z.object({
+      query: import_zod.z.string().describe(
+        "The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
+      ),
       libraryName: import_zod.z.string().describe("Library name to search for and retrieve a Context7-compatible library ID.")
     }),
-    execute: async ({ libraryName }) => {
+    execute: async ({ query, libraryName }) => {
       try {
         const client = getClient();
-        const response = await client.searchLibrary(libraryName);
-        if (!response.results || response.results.length === 0) {
-          return {
-            success: false,
-            error: "No libraries found matching your query.",
-            suggestions: "Try a different search term or check the library name."
-          };
+        const results = await client.searchLibrary(query, libraryName, { type: "txt" });
+        if (!results || results.length === 0) {
+          return `No libraries found matching "${libraryName}". Try a different search term or check the library name.`;
         }
-        return {
-          success: true,
-          results: response.results,
-          totalResults: response.results.length
-        };
+        return results;
       } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : "Failed to search libraries",
-          suggestions: "Check your API key and try again, or try a different search term."
-        };
+        const errorMessage = error instanceof Error ? error.message : "Failed to search libraries";
+        return `Error searching for libraries: ${errorMessage}. Check your API key and try again.`;
       }
     }
   });
 }
 
-// src/tools/get-library-docs.ts
+// src/tools/query-docs.ts
 var import_ai2 = require("ai");
 var import_zod2 = require("zod");
 var import_context7_sdk2 = require("@upstash/context7-sdk");
-function getLibraryDocs(config = {}) {
-  const { apiKey, defaultMaxResults = 10 } = config;
+function queryDocs(config = {}) {
+  const { apiKey } = config;
   const getClient = () => new import_context7_sdk2.Context7({ apiKey });
   return (0, import_ai2.tool)({
-    description: GET_LIBRARY_DOCS_DESCRIPTION,
+    description: QUERY_DOCS_DESCRIPTION,
     inputSchema: import_zod2.z.object({
       libraryId: import_zod2.z.string().describe(
-        "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibrary' or directly from user query in the format '/org/project' or '/org/project/version'."
+        "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibraryId' or directly from user query in the format '/org/project' or '/org/project/version'."
       ),
-      mode: import_zod2.z.enum(["code", "info"]).optional().default("code").describe(
-        "Documentation mode: 'code' for API references and code examples (default), 'info' for conceptual guides, narrative information, and architectural questions."
-      ),
-      topic: import_zod2.z.string().optional().describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
-      page: import_zod2.z.number().int().min(1).max(10).optional().describe(
-        "Page number for pagination (start: 1, default: 1). If the context is not sufficient, try page=2, page=3, page=4, etc. with the same topic."
+      query: import_zod2.z.string().describe(
+        "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
       )
     }),
-    execute: async ({
-      libraryId,
-      mode = "code",
-      topic,
-      page = 1
-    }) => {
+    execute: async ({ libraryId, query }) => {
       try {
         const client = getClient();
-        const baseOptions = {
-          page,
-          limit: defaultMaxResults,
-          topic: topic?.trim() || void 0
-        };
-        const response = mode === "info" ? await client.getDocs(libraryId, { ...baseOptions, mode: "info" }) : await client.getDocs(libraryId, { ...baseOptions, mode: "code" });
-        if (!response.snippets?.length) {
-          return {
-            success: false,
-            error: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolveLibrary' with the package name you wish to retrieve documentation for.",
-            libraryId
-          };
+        const documentation = await client.getContext(query, libraryId, { type: "txt" });
+        if (!documentation || documentation.length === 0) {
+          return `No documentation found for library "${libraryId}". This might have happened because you used an invalid Context7-compatible library ID. Use 'resolveLibraryId' to get a valid ID.`;
         }
-        return {
-          success: true,
-          libraryId,
-          snippets: response.snippets,
-          pagination: response.pagination,
-          totalTokens: response.totalTokens
-        };
+        return documentation;
       } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : "Failed to fetch documentation",
-          libraryId
-        };
+        const errorMessage = error instanceof Error ? error.message : "Failed to fetch documentation";
+        return `Error fetching documentation for "${libraryId}": ${errorMessage}`;
       }
     }
   });
@@ -200,24 +167,16 @@ function getLibraryDocs(config = {}) {
 // src/agents/context7.ts
 var Context7Agent = class extends import_ai3.Experimental_Agent {
   constructor(config) {
-    const {
-      model,
-      stopWhen = (0, import_ai3.stepCountIs)(5),
-      system,
-      apiKey,
-      defaultMaxResults,
-      tools,
-      ...agentSettings
-    } = config;
-    const context7Config = { apiKey, defaultMaxResults };
+    const { model, stopWhen = (0, import_ai3.stepCountIs)(5), system, apiKey, tools, ...agentSettings } = config;
+    const context7Config = { apiKey };
     super({
       ...agentSettings,
       model,
       system: system || AGENT_PROMPT,
       tools: {
         ...tools,
-        resolveLibrary: resolveLibrary(context7Config),
-        getLibraryDocs: getLibraryDocs(context7Config)
+        resolveLibraryId: resolveLibraryId(context7Config),
+        queryDocs: queryDocs(context7Config)
       },
       stopWhen
     });
@@ -227,9 +186,9 @@ var Context7Agent = class extends import_ai3.Experimental_Agent {
 0 && (module.exports = {
   AGENT_PROMPT,
   Context7Agent,
-  GET_LIBRARY_DOCS_DESCRIPTION,
-  RESOLVE_LIBRARY_DESCRIPTION,
+  QUERY_DOCS_DESCRIPTION,
+  RESOLVE_LIBRARY_ID_DESCRIPTION,
   SYSTEM_PROMPT,
-  getLibraryDocs,
-  resolveLibrary
+  queryDocs,
+  resolveLibraryId
 });

package/dist/index.d.cts

@@ -1,7 +1,6 @@
 export { Context7Agent, Context7AgentConfig } from './agent.cjs';
 import * as ai from 'ai';
-import * as _upstash_context7_sdk from '@upstash/context7-sdk';
-export { CodeDocsResponse, InfoDocsResponse, Pagination, SearchLibraryResponse, SearchResult, TextDocsResponse } from '@upstash/context7-sdk';
+export { Context7Config, Documentation, GetContextOptions, Library } from '@upstash/context7-sdk';
 
 /**
  * Configuration for Context7 tools
@@ -11,11 +10,6 @@ interface Context7ToolsConfig {
      * Context7 API key. If not provided, will use CONTEXT7_API_KEY environment variable.
      */
     apiKey?: string;
-    /**
-     * Default maximum number of documentation results per page.
-     * @default 10
-     */
-    defaultMaxResults?: number;
 }
 
 /**
@@ -29,7 +23,7 @@ interface Context7ToolsConfig {
  *
  * @example
  * ```typescript
- * import { resolveLibrary, getLibraryDocs } from '@upstash/context7-tools-ai-sdk';
+ * import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
  * import { generateText, stepCountIs } from 'ai';
  * import { openai } from '@ai-sdk/openai';
  *
@@ -37,28 +31,17 @@ interface Context7ToolsConfig {
  *   model: openai('gpt-4o'),
  *   prompt: 'Find React documentation about hooks',
  *   tools: {
- *     resolveLibrary: resolveLibrary(),
- *     getLibraryDocs: getLibraryDocs(),
+ *     resolveLibraryId: resolveLibraryId(),
+ *     queryDocs: queryDocs(),
  *   },
  *   stopWhen: stepCountIs(5),
  * });
  * ```
  */
-declare function resolveLibrary(config?: Context7ToolsConfig): ai.Tool<{
+declare function resolveLibraryId(config?: Context7ToolsConfig): ai.Tool<{
+    query: string;
     libraryName: string;
-}, {
-    success: boolean;
-    error: string;
-    suggestions: string;
-    results?: undefined;
-    totalResults?: undefined;
-} | {
-    success: boolean;
-    results: _upstash_context7_sdk.SearchResult[];
-    totalResults: number;
-    error?: undefined;
-    suggestions?: undefined;
-}>;
+}, string>;
 
 /**
  * Tool to fetch documentation for a library using its Context7 library ID.
@@ -71,7 +54,7 @@ declare function resolveLibrary(config?: Context7ToolsConfig): ai.Tool<{
  *
  * @example
  * ```typescript
- * import { resolveLibrary, getLibraryDocs } from '@upstash/context7-tools-ai-sdk';
+ * import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
  * import { generateText, stepCountIs } from 'ai';
  * import { openai } from '@ai-sdk/openai';
  *
@@ -79,33 +62,17 @@ declare function resolveLibrary(config?: Context7ToolsConfig): ai.Tool<{
  *   model: openai('gpt-4o'),
  *   prompt: 'Find React documentation about hooks',
  *   tools: {
- *     resolveLibrary: resolveLibrary(),
- *     getLibraryDocs: getLibraryDocs(),
+ *     resolveLibraryId: resolveLibraryId(),
+ *     queryDocs: queryDocs(),
  *   },
  *   stopWhen: stepCountIs(5),
  * });
  * ```
  */
-declare function getLibraryDocs(config?: Context7ToolsConfig): ai.Tool<{
-    libraryId: string;
-    mode?: "code" | "info";
-    topic?: string;
-    page?: number;
-}, {
-    success: boolean;
-    error: string;
-    libraryId: string;
-    snippets?: undefined;
-    pagination?: undefined;
-    totalTokens?: undefined;
-} | {
-    success: boolean;
+declare function queryDocs(config?: Context7ToolsConfig): ai.Tool<{
+    query: string;
     libraryId: string;
-    snippets: _upstash_context7_sdk.CodeSnippet[] | _upstash_context7_sdk.InfoSnippet[];
-    pagination: _upstash_context7_sdk.Pagination;
-    totalTokens: number;
-    error?: undefined;
-}>;
+}, string>;
 
 /**
  * System prompts for Context7 AI SDK agents
@@ -117,14 +84,14 @@ declare const SYSTEM_PROMPT = "You are a documentation search assistant powered
 /**
  * Detailed multi-step workflow prompt for comprehensive documentation retrieval
  */
-declare const AGENT_PROMPT = "You are a documentation search assistant powered by Context7.\n\nCRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:\n\nStep 1: ALWAYS start by calling 'resolveLibrary' with the library name from the user's query\n   - Extract the main library/framework name (e.g., \"React\", \"Next.js\", \"Vue\")\n   - Call resolveLibrary with just the library name\n   - Review ALL the search results returned\n\nStep 2: Analyze the results from resolveLibrary and select the BEST library ID based on:\n   - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)\n   - Name similarity to what the user is looking for\n   - Description relevance\n   - Source reputation (High/Medium is better)\n   - Code snippet coverage (higher is better)\n   - Benchmark score (higher is better)\n\nStep 3: Call 'getLibraryDocs' with the selected library ID\n   - Use the exact library ID from the resolveLibrary results\n   - ALWAYS extract and include a relevant topic from the user's query (e.g., \"Server-Side Rendering\", \"routing\", \"authentication\")\n   - Start with page=1 (default)\n\nStep 4: If the documentation from page 1 isn't sufficient, call 'getLibraryDocs' again with page=2\n   - Use the same library ID and the SAME topic from step 3\n   - This gives you more comprehensive documentation\n\nStep 5: Provide a clear answer with code examples from the documentation\n\nIMPORTANT:\n- You MUST call resolveLibrary first before calling getLibraryDocs\n- Do NOT skip resolveLibrary - it helps you find the correct official documentation\n- Always cite which library ID you used";
+declare const AGENT_PROMPT = "You are a documentation search assistant powered by Context7.\n\nCRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:\n\nStep 1: ALWAYS start by calling 'resolveLibraryId' with the library name from the user's query\n   - Extract the main library/framework name (e.g., \"React\", \"Next.js\", \"Vue\")\n   - Call resolveLibraryId with just the library name\n   - Review ALL the search results returned\n\nStep 2: Analyze the results from resolveLibraryId and select the BEST library ID based on:\n   - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)\n   - Name similarity to what the user is looking for\n   - Description relevance\n   - Source reputation (High/Medium is better)\n   - Code snippet coverage (higher is better)\n   - Benchmark score (higher is better)\n\nStep 3: Call 'queryDocs' with the selected library ID and the user's query\n   - Use the exact library ID from the resolveLibraryId results\n   - Include the user's original question as the query parameter\n\nStep 4: Provide a clear answer with code examples from the documentation\n\nIMPORTANT:\n- You MUST call resolveLibraryId first before calling queryDocs\n- Do NOT skip resolveLibraryId - it helps you find the correct official documentation\n- Do not call either tool more than 3 times per question\n- Always cite which library ID you used";
 /**
  * Library resolution tool description
  */
-declare const RESOLVE_LIBRARY_DESCRIPTION = "Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.\n\nYou MUST call this function before 'getLibraryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.\n\nSelection Process:\n1. Analyze the query to understand what library/package the user is looking for\n2. Return the most relevant match based on:\n- Name similarity to the query (exact matches prioritized)\n- Description relevance to the query's intent\n- Documentation coverage (prioritize libraries with higher Code Snippet counts)\n- Source reputation (consider libraries with High or Medium reputation more authoritative)\n- Benchmark Score: Quality indicator (100 is the highest score)\n\nResponse Format:\n- Return the selected library ID in a clearly marked section\n- Provide a brief explanation for why this library was chosen\n- If multiple good matches exist, acknowledge this but proceed with the most relevant one\n- If no good matches exist, clearly state this and suggest query refinements\n\nFor ambiguous queries, request clarification before proceeding with a best-guess match.";
+declare const RESOLVE_LIBRARY_ID_DESCRIPTION = "Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.\n\nYou MUST call this function before 'queryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.\n\nSelection Process:\n1. Analyze the query to understand what library/package the user is looking for\n2. Return the most relevant match based on:\n- Name similarity to the query (exact matches prioritized)\n- Description relevance to the query's intent\n- Documentation coverage (prioritize libraries with higher Code Snippet counts)\n- Source reputation (consider libraries with High or Medium reputation more authoritative)\n- Benchmark Score: Quality indicator (100 is the highest score)\n\nResponse Format:\n- Return the selected library ID in a clearly marked section\n- Provide a brief explanation for why this library was chosen\n- If multiple good matches exist, acknowledge this but proceed with the most relevant one\n- If no good matches exist, clearly state this and suggest query refinements\n\nFor ambiguous queries, request clarification before proceeding with a best-guess match.\n\nIMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.";
 /**
- * Get library docs tool description
+ * Query docs tool description
  */
-declare const GET_LIBRARY_DOCS_DESCRIPTION = "Fetches up-to-date documentation for a library. You must call 'resolveLibrary' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. Use mode='code' (default) for API references and code examples, or mode='info' for conceptual guides, narrative information, and architectural questions.";
+declare const QUERY_DOCS_DESCRIPTION = "Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.\n\nYou must call 'resolveLibraryId' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.\n\nIMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.";
 
-export { AGENT_PROMPT, type Context7ToolsConfig, GET_LIBRARY_DOCS_DESCRIPTION, RESOLVE_LIBRARY_DESCRIPTION, SYSTEM_PROMPT, getLibraryDocs, resolveLibrary };
+export { AGENT_PROMPT, type Context7ToolsConfig, QUERY_DOCS_DESCRIPTION, RESOLVE_LIBRARY_ID_DESCRIPTION, SYSTEM_PROMPT, queryDocs, resolveLibraryId };

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 export { Context7Agent, Context7AgentConfig } from './agent.js';
 import * as ai from 'ai';
-import * as _upstash_context7_sdk from '@upstash/context7-sdk';
-export { CodeDocsResponse, InfoDocsResponse, Pagination, SearchLibraryResponse, SearchResult, TextDocsResponse } from '@upstash/context7-sdk';
+export { Context7Config, Documentation, GetContextOptions, Library } from '@upstash/context7-sdk';
 
 /**
  * Configuration for Context7 tools
@@ -11,11 +10,6 @@ interface Context7ToolsConfig {
      * Context7 API key. If not provided, will use CONTEXT7_API_KEY environment variable.
      */
     apiKey?: string;
-    /**
-     * Default maximum number of documentation results per page.
-     * @default 10
-     */
-    defaultMaxResults?: number;
 }
 
 /**
@@ -29,7 +23,7 @@ interface Context7ToolsConfig {
  *
  * @example
  * ```typescript
- * import { resolveLibrary, getLibraryDocs } from '@upstash/context7-tools-ai-sdk';
+ * import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
  * import { generateText, stepCountIs } from 'ai';
  * import { openai } from '@ai-sdk/openai';
  *
@@ -37,28 +31,17 @@ interface Context7ToolsConfig {
  *   model: openai('gpt-4o'),
  *   prompt: 'Find React documentation about hooks',
  *   tools: {
- *     resolveLibrary: resolveLibrary(),
- *     getLibraryDocs: getLibraryDocs(),
+ *     resolveLibraryId: resolveLibraryId(),
+ *     queryDocs: queryDocs(),
  *   },
  *   stopWhen: stepCountIs(5),
  * });
  * ```
  */
-declare function resolveLibrary(config?: Context7ToolsConfig): ai.Tool<{
+declare function resolveLibraryId(config?: Context7ToolsConfig): ai.Tool<{
+    query: string;
     libraryName: string;
-}, {
-    success: boolean;
-    error: string;
-    suggestions: string;
-    results?: undefined;
-    totalResults?: undefined;
-} | {
-    success: boolean;
-    results: _upstash_context7_sdk.SearchResult[];
-    totalResults: number;
-    error?: undefined;
-    suggestions?: undefined;
-}>;
+}, string>;
 
 /**
  * Tool to fetch documentation for a library using its Context7 library ID.
@@ -71,7 +54,7 @@ declare function resolveLibrary(config?: Context7ToolsConfig): ai.Tool<{
  *
  * @example
  * ```typescript
- * import { resolveLibrary, getLibraryDocs } from '@upstash/context7-tools-ai-sdk';
+ * import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
  * import { generateText, stepCountIs } from 'ai';
  * import { openai } from '@ai-sdk/openai';
  *
@@ -79,33 +62,17 @@ declare function resolveLibrary(config?: Context7ToolsConfig): ai.Tool<{
  *   model: openai('gpt-4o'),
  *   prompt: 'Find React documentation about hooks',
  *   tools: {
- *     resolveLibrary: resolveLibrary(),
- *     getLibraryDocs: getLibraryDocs(),
+ *     resolveLibraryId: resolveLibraryId(),
+ *     queryDocs: queryDocs(),
  *   },
  *   stopWhen: stepCountIs(5),
  * });
  * ```
  */
-declare function getLibraryDocs(config?: Context7ToolsConfig): ai.Tool<{
-    libraryId: string;
-    mode?: "code" | "info";
-    topic?: string;
-    page?: number;
-}, {
-    success: boolean;
-    error: string;
-    libraryId: string;
-    snippets?: undefined;
-    pagination?: undefined;
-    totalTokens?: undefined;
-} | {
-    success: boolean;
+declare function queryDocs(config?: Context7ToolsConfig): ai.Tool<{
+    query: string;
     libraryId: string;
-    snippets: _upstash_context7_sdk.CodeSnippet[] | _upstash_context7_sdk.InfoSnippet[];
-    pagination: _upstash_context7_sdk.Pagination;
-    totalTokens: number;
-    error?: undefined;
-}>;
+}, string>;
 
 /**
  * System prompts for Context7 AI SDK agents
@@ -117,14 +84,14 @@ declare const SYSTEM_PROMPT = "You are a documentation search assistant powered
 /**
  * Detailed multi-step workflow prompt for comprehensive documentation retrieval
  */
-declare const AGENT_PROMPT = "You are a documentation search assistant powered by Context7.\n\nCRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:\n\nStep 1: ALWAYS start by calling 'resolveLibrary' with the library name from the user's query\n   - Extract the main library/framework name (e.g., \"React\", \"Next.js\", \"Vue\")\n   - Call resolveLibrary with just the library name\n   - Review ALL the search results returned\n\nStep 2: Analyze the results from resolveLibrary and select the BEST library ID based on:\n   - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)\n   - Name similarity to what the user is looking for\n   - Description relevance\n   - Source reputation (High/Medium is better)\n   - Code snippet coverage (higher is better)\n   - Benchmark score (higher is better)\n\nStep 3: Call 'getLibraryDocs' with the selected library ID\n   - Use the exact library ID from the resolveLibrary results\n   - ALWAYS extract and include a relevant topic from the user's query (e.g., \"Server-Side Rendering\", \"routing\", \"authentication\")\n   - Start with page=1 (default)\n\nStep 4: If the documentation from page 1 isn't sufficient, call 'getLibraryDocs' again with page=2\n   - Use the same library ID and the SAME topic from step 3\n   - This gives you more comprehensive documentation\n\nStep 5: Provide a clear answer with code examples from the documentation\n\nIMPORTANT:\n- You MUST call resolveLibrary first before calling getLibraryDocs\n- Do NOT skip resolveLibrary - it helps you find the correct official documentation\n- Always cite which library ID you used";
+declare const AGENT_PROMPT = "You are a documentation search assistant powered by Context7.\n\nCRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:\n\nStep 1: ALWAYS start by calling 'resolveLibraryId' with the library name from the user's query\n   - Extract the main library/framework name (e.g., \"React\", \"Next.js\", \"Vue\")\n   - Call resolveLibraryId with just the library name\n   - Review ALL the search results returned\n\nStep 2: Analyze the results from resolveLibraryId and select the BEST library ID based on:\n   - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)\n   - Name similarity to what the user is looking for\n   - Description relevance\n   - Source reputation (High/Medium is better)\n   - Code snippet coverage (higher is better)\n   - Benchmark score (higher is better)\n\nStep 3: Call 'queryDocs' with the selected library ID and the user's query\n   - Use the exact library ID from the resolveLibraryId results\n   - Include the user's original question as the query parameter\n\nStep 4: Provide a clear answer with code examples from the documentation\n\nIMPORTANT:\n- You MUST call resolveLibraryId first before calling queryDocs\n- Do NOT skip resolveLibraryId - it helps you find the correct official documentation\n- Do not call either tool more than 3 times per question\n- Always cite which library ID you used";
 /**
  * Library resolution tool description
  */
-declare const RESOLVE_LIBRARY_DESCRIPTION = "Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.\n\nYou MUST call this function before 'getLibraryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.\n\nSelection Process:\n1. Analyze the query to understand what library/package the user is looking for\n2. Return the most relevant match based on:\n- Name similarity to the query (exact matches prioritized)\n- Description relevance to the query's intent\n- Documentation coverage (prioritize libraries with higher Code Snippet counts)\n- Source reputation (consider libraries with High or Medium reputation more authoritative)\n- Benchmark Score: Quality indicator (100 is the highest score)\n\nResponse Format:\n- Return the selected library ID in a clearly marked section\n- Provide a brief explanation for why this library was chosen\n- If multiple good matches exist, acknowledge this but proceed with the most relevant one\n- If no good matches exist, clearly state this and suggest query refinements\n\nFor ambiguous queries, request clarification before proceeding with a best-guess match.";
+declare const RESOLVE_LIBRARY_ID_DESCRIPTION = "Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.\n\nYou MUST call this function before 'queryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.\n\nSelection Process:\n1. Analyze the query to understand what library/package the user is looking for\n2. Return the most relevant match based on:\n- Name similarity to the query (exact matches prioritized)\n- Description relevance to the query's intent\n- Documentation coverage (prioritize libraries with higher Code Snippet counts)\n- Source reputation (consider libraries with High or Medium reputation more authoritative)\n- Benchmark Score: Quality indicator (100 is the highest score)\n\nResponse Format:\n- Return the selected library ID in a clearly marked section\n- Provide a brief explanation for why this library was chosen\n- If multiple good matches exist, acknowledge this but proceed with the most relevant one\n- If no good matches exist, clearly state this and suggest query refinements\n\nFor ambiguous queries, request clarification before proceeding with a best-guess match.\n\nIMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.";
 /**
- * Get library docs tool description
+ * Query docs tool description
  */
-declare const GET_LIBRARY_DOCS_DESCRIPTION = "Fetches up-to-date documentation for a library. You must call 'resolveLibrary' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. Use mode='code' (default) for API references and code examples, or mode='info' for conceptual guides, narrative information, and architectural questions.";
+declare const QUERY_DOCS_DESCRIPTION = "Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.\n\nYou must call 'resolveLibraryId' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.\n\nIMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.";
 
-export { AGENT_PROMPT, type Context7ToolsConfig, GET_LIBRARY_DOCS_DESCRIPTION, RESOLVE_LIBRARY_DESCRIPTION, SYSTEM_PROMPT, getLibraryDocs, resolveLibrary };
+export { AGENT_PROMPT, type Context7ToolsConfig, QUERY_DOCS_DESCRIPTION, RESOLVE_LIBRARY_ID_DESCRIPTION, SYSTEM_PROMPT, queryDocs, resolveLibraryId };

package/dist/index.js

@@ -1,18 +1,18 @@
 import {
   AGENT_PROMPT,
   Context7Agent,
-  GET_LIBRARY_DOCS_DESCRIPTION,
-  RESOLVE_LIBRARY_DESCRIPTION,
+  QUERY_DOCS_DESCRIPTION,
+  RESOLVE_LIBRARY_ID_DESCRIPTION,
   SYSTEM_PROMPT,
-  getLibraryDocs,
-  resolveLibrary
-} from "./chunk-AMSBQOUU.js";
+  queryDocs,
+  resolveLibraryId
+} from "./chunk-5OOZPW2Y.js";
 export {
   AGENT_PROMPT,
   Context7Agent,
-  GET_LIBRARY_DOCS_DESCRIPTION,
-  RESOLVE_LIBRARY_DESCRIPTION,
+  QUERY_DOCS_DESCRIPTION,
+  RESOLVE_LIBRARY_ID_DESCRIPTION,
   SYSTEM_PROMPT,
-  getLibraryDocs,
-  resolveLibrary
+  queryDocs,
+  resolveLibraryId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/context7-tools-ai-sdk",
-  "version": "0.2.0-canary-20251209084107",
+  "version": "0.2.0",
   "description": "Context7 tools for Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,7 +22,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@upstash/context7-sdk": ">=0.1.0",
+    "@upstash/context7-sdk": ">=0.3.0",
     "ai": ">=5.0.0",
     "zod": ">=3.24.0"
   },
@@ -30,12 +30,12 @@
     "ai": "^5.0.0",
     "zod": "^3.24.0",
     "@ai-sdk/amazon-bedrock": "^3.0.55",
-    "@types/node": "^22.13.14",
+    "@types/node": "^25.0.3",
     "dotenv": "^17.2.3",
     "tsup": "^8.5.1",
     "typescript": "^5.8.2",
     "vitest": "^4.0.13",
-    "@upstash/context7-sdk": "0.1.0"
+    "@upstash/context7-sdk": "0.3.0"
   },
   "repository": {
     "type": "git",

package/dist/chunk-AMSBQOUU.js

@@ -1,206 +0,0 @@
-// src/agents/context7.ts
-import {
-  Experimental_Agent as Agent,
-  stepCountIs
-} from "ai";
-
-// src/tools/resolve-library.ts
-import { tool } from "ai";
-import { z } from "zod";
-import { Context7 } from "@upstash/context7-sdk";
-
-// src/prompts/system.ts
-var SYSTEM_PROMPT = `You are a documentation search assistant powered by Context7.
-
-Your role is to help users find accurate, up-to-date documentation for libraries and frameworks.
-
-When answering questions:
-1. Search for the relevant library documentation
-2. Provide code examples when available
-3. Cite your sources by mentioning the library ID used`;
-var AGENT_PROMPT = `You are a documentation search assistant powered by Context7.
-
-CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:
-
-Step 1: ALWAYS start by calling 'resolveLibrary' with the library name from the user's query
-   - Extract the main library/framework name (e.g., "React", "Next.js", "Vue")
-   - Call resolveLibrary with just the library name
-   - Review ALL the search results returned
-
-Step 2: Analyze the results from resolveLibrary and select the BEST library ID based on:
-   - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js)
-   - Name similarity to what the user is looking for
-   - Description relevance
-   - Source reputation (High/Medium is better)
-   - Code snippet coverage (higher is better)
-   - Benchmark score (higher is better)
-
-Step 3: Call 'getLibraryDocs' with the selected library ID
-   - Use the exact library ID from the resolveLibrary results
-   - ALWAYS extract and include a relevant topic from the user's query (e.g., "Server-Side Rendering", "routing", "authentication")
-   - Start with page=1 (default)
-
-Step 4: If the documentation from page 1 isn't sufficient, call 'getLibraryDocs' again with page=2
-   - Use the same library ID and the SAME topic from step 3
-   - This gives you more comprehensive documentation
-
-Step 5: Provide a clear answer with code examples from the documentation
-
-IMPORTANT:
-- You MUST call resolveLibrary first before calling getLibraryDocs
-- Do NOT skip resolveLibrary - it helps you find the correct official documentation
-- Always cite which library ID you used`;
-var RESOLVE_LIBRARY_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.
-
-You MUST call this function before 'getLibraryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
-
-Selection Process:
-1. Analyze the query to understand what library/package the user is looking for
-2. Return the most relevant match based on:
-- Name similarity to the query (exact matches prioritized)
-- Description relevance to the query's intent
-- Documentation coverage (prioritize libraries with higher Code Snippet counts)
-- Source reputation (consider libraries with High or Medium reputation more authoritative)
-- Benchmark Score: Quality indicator (100 is the highest score)
-
-Response Format:
-- Return the selected library ID in a clearly marked section
-- Provide a brief explanation for why this library was chosen
-- If multiple good matches exist, acknowledge this but proceed with the most relevant one
-- If no good matches exist, clearly state this and suggest query refinements
-
-For ambiguous queries, request clarification before proceeding with a best-guess match.`;
-var GET_LIBRARY_DOCS_DESCRIPTION = "Fetches up-to-date documentation for a library. You must call 'resolveLibrary' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. Use mode='code' (default) for API references and code examples, or mode='info' for conceptual guides, narrative information, and architectural questions.";
-
-// src/tools/resolve-library.ts
-function resolveLibrary(config = {}) {
-  const { apiKey } = config;
-  const getClient = () => new Context7({ apiKey });
-  return tool({
-    description: RESOLVE_LIBRARY_DESCRIPTION,
-    inputSchema: z.object({
-      libraryName: z.string().describe("Library name to search for and retrieve a Context7-compatible library ID.")
-    }),
-    execute: async ({ libraryName }) => {
-      try {
-        const client = getClient();
-        const response = await client.searchLibrary(libraryName);
-        if (!response.results || response.results.length === 0) {
-          return {
-            success: false,
-            error: "No libraries found matching your query.",
-            suggestions: "Try a different search term or check the library name."
-          };
-        }
-        return {
-          success: true,
-          results: response.results,
-          totalResults: response.results.length
-        };
-      } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : "Failed to search libraries",
-          suggestions: "Check your API key and try again, or try a different search term."
-        };
-      }
-    }
-  });
-}
-
-// src/tools/get-library-docs.ts
-import { tool as tool2 } from "ai";
-import { z as z2 } from "zod";
-import { Context7 as Context72 } from "@upstash/context7-sdk";
-function getLibraryDocs(config = {}) {
-  const { apiKey, defaultMaxResults = 10 } = config;
-  const getClient = () => new Context72({ apiKey });
-  return tool2({
-    description: GET_LIBRARY_DOCS_DESCRIPTION,
-    inputSchema: z2.object({
-      libraryId: z2.string().describe(
-        "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibrary' or directly from user query in the format '/org/project' or '/org/project/version'."
-      ),
-      mode: z2.enum(["code", "info"]).optional().default("code").describe(
-        "Documentation mode: 'code' for API references and code examples (default), 'info' for conceptual guides, narrative information, and architectural questions."
-      ),
-      topic: z2.string().optional().describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
-      page: z2.number().int().min(1).max(10).optional().describe(
-        "Page number for pagination (start: 1, default: 1). If the context is not sufficient, try page=2, page=3, page=4, etc. with the same topic."
-      )
-    }),
-    execute: async ({
-      libraryId,
-      mode = "code",
-      topic,
-      page = 1
-    }) => {
-      try {
-        const client = getClient();
-        const baseOptions = {
-          page,
-          limit: defaultMaxResults,
-          topic: topic?.trim() || void 0
-        };
-        const response = mode === "info" ? await client.getDocs(libraryId, { ...baseOptions, mode: "info" }) : await client.getDocs(libraryId, { ...baseOptions, mode: "code" });
-        if (!response.snippets?.length) {
-          return {
-            success: false,
-            error: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolveLibrary' with the package name you wish to retrieve documentation for.",
-            libraryId
-          };
-        }
-        return {
-          success: true,
-          libraryId,
-          snippets: response.snippets,
-          pagination: response.pagination,
-          totalTokens: response.totalTokens
-        };
-      } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : "Failed to fetch documentation",
-          libraryId
-        };
-      }
-    }
-  });
-}
-
-// src/agents/context7.ts
-var Context7Agent = class extends Agent {
-  constructor(config) {
-    const {
-      model,
-      stopWhen = stepCountIs(5),
-      system,
-      apiKey,
-      defaultMaxResults,
-      tools,
-      ...agentSettings
-    } = config;
-    const context7Config = { apiKey, defaultMaxResults };
-    super({
-      ...agentSettings,
-      model,
-      system: system || AGENT_PROMPT,
-      tools: {
-        ...tools,
-        resolveLibrary: resolveLibrary(context7Config),
-        getLibraryDocs: getLibraryDocs(context7Config)
-      },
-      stopWhen
-    });
-  }
-};
-
-export {
-  SYSTEM_PROMPT,
-  AGENT_PROMPT,
-  RESOLVE_LIBRARY_DESCRIPTION,
-  GET_LIBRARY_DOCS_DESCRIPTION,
-  resolveLibrary,
-  getLibraryDocs,
-  Context7Agent
-};