CTX7-1872: Improve Context7 documentation queries

.changeset/giant-numbers-divide.md

@@ -0,0 +1,8 @@
+---
+"@upstash/context7-tools-ai-sdk": patch
+"ctx7": patch
+"@upstash/context7-mcp": patch
+"@upstash/context7-pi": patch
+---
+
+Improve query prompts so agents request relevant library documentation instead of passing the task to complete.

packages/cli/src/commands/docs.ts

@@ -219,7 +219,7 @@ export function registerDocsCommands(program: Command): void {
   program
     .command("library")
     .argument("<name>", "Library name to search for")
-    .argument("[query]", "Question or task for relevance ranking")
+    .argument("[query]", "What to look up in the library's documentation")
     .option("--json", "Output as JSON")
     .description("Resolve a library name to a Context7 library ID")
     .action(async (name: string, query: string | undefined, options: { json?: boolean }) => {

packages/cli/src/setup/templates.ts

@@ -9,9 +9,9 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo
 
 ## Steps
 
-1. \`resolve-library-id\` with the library name and the user's question. Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs")
+1. \`resolve-library-id\` with the library name and what to look up in the library's documentation. Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs")
 2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). Use version-specific IDs when the user mentions a version
-3. \`query-docs\` with the selected library ID and the user's full question (not single words), scoped to a single concept. If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate \`query-docs\` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic
+3. \`query-docs\` with the selected library ID and what to look up in the library's documentation (not single words), scoped to a single concept. If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate \`query-docs\` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic
 4. Answer using the fetched docs
 `;
 
@@ -21,12 +21,12 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo
 
 ## Steps
 
-1. Resolve library: \`npx ctx7@latest library <name> "<user's question>"\`
+1. Resolve library: \`npx ctx7@latest library <name> "<what to look up>"\`
 2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try the full name with punctuation (e.g., "next.js" not "nextjs")
-3. Fetch docs: \`npx ctx7@latest docs <libraryId> "<user's question>"\` — run a separate \`docs\` command per distinct concept if the question spans multiple topics, unless it's about how they interact
+3. Fetch docs: \`npx ctx7@latest docs <libraryId> "<what to look up>"\` — run a separate \`docs\` command per distinct concept if the question spans multiple topics, unless it's about how they interact
 4. Answer using the fetched documentation
 
-You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Use the user's full question as the query — specific and detailed queries return better results than vague single words, but keep each query to a single concept unless the question is about how concepts interact; combined multi-topic queries dilute ranking and return shallow results for each topic. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.
+You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Be specific about what to look up in the library's documentation — specific and detailed queries return better results than vague single words, but keep each query to a single concept unless the question is about how concepts interact; combined multi-topic queries dilute ranking and return shallow results for each topic. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.
 
 For version-specific docs, use \`/org/project/version\` from the \`library\` output (e.g., \`/vercel/next.js/v14.3.0\`).
 

packages/mcp/src/index.ts

@@ -172,7 +172,7 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
         query: z
           .string()
           .describe(
-            "The question or task you need help with. This is used to rank library results by relevance to what the user is trying to accomplish. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."
+            "What to look up in the library's documentation. This is used to rank library results by relevance to what the user is trying to accomplish. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."
           ),
         libraryName: z
           .string()
@@ -236,7 +236,7 @@ Do not call this tool more than 3 times per question.`,
         query: z
           .string()
           .describe(
-            "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."
+            "What to look up in the library's documentation, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."
           ),
       },
       annotations: {

packages/pi/__tests__/extension.test.ts

@@ -52,5 +52,5 @@ describe("live Context7 API", () => {
     );
     expect(result.content[0].type).toBe("text");
     expect((result.content[0] as { text: string }).text).toMatch(/react/i);
-  });
+  }, 15_000);
 });

packages/pi/lib/prompts.ts

@@ -40,7 +40,7 @@ For ambiguous queries, request clarification before proceeding with a best-guess
 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.`;
 
 export const RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION =
-  "The question or task you need help with. This is used to rank library results by relevance to what the user is trying to accomplish. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.";
+  "What to look up in the library's documentation. This is used to rank library results by relevance to what the user is trying to accomplish. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.";
 
 export const RESOLVE_LIBRARY_ID_LIBRARY_NAME_DESCRIPTION =
   "Library name to search for and retrieve a Context7-compatible library ID. Use the official library name with proper punctuation — e.g., 'Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio', 'Three.js' instead of 'threejs'.";
@@ -57,4 +57,4 @@ export const QUERY_DOCS_LIBRARY_ID_DESCRIPTION =
   "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'.";
 
 export const QUERY_DOCS_QUERY_DESCRIPTION =
-  "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.";
+  "What to look up in the library's documentation, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.";

packages/pi/prompts/c7-docs.md

@@ -5,8 +5,9 @@ argument-hint: <library> <question>
 
 Look up documentation for `$1` using Context7.
 
-1. Call the `resolve-library-id` tool with `libraryName="$1"` and `query="${@:2}"` to find the best matching library.
-2. Call the `query-docs` tool with the selected library ID and `query="${@:2}"`.
-3. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used.
+1. Determine what to look up in the library's documentation from `${@:2}`.
+2. Call the `resolve-library-id` tool with `libraryName="$1"` and what to look up as `query` to find the best matching library.
+3. Call the `query-docs` tool with the selected library ID and what to look up as `query`.
+4. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used.
 
-If `$1` is already in `/org/project` or `/org/project/version` format, skip step 1 and call `query-docs` directly.
+If `$1` is already in `/org/project` or `/org/project/version` format, skip library resolution and call `query-docs` directly.

packages/pi/skills/context7-docs/SKILL.md

@@ -32,8 +32,8 @@ Reach for these tools whenever a question involves a specific library, framework
 
 ## Workflow
 
-1. **Resolve the library ID.** Call `resolve-library-id` with the library name and the user's question. The tool returns matching libraries with their Context7 IDs (`/org/project` format), descriptions, snippet counts, and quality scores. Pick the best match — prioritize official sources, name match, and high benchmark scores.
-2. **Query the docs.** Call `query-docs` with the chosen library ID and the user's question, scoped to a single concept — if the question spans multiple distinct concepts, make a separate call per concept with the same library ID, unless the question is about how the concepts interact. The tool returns documentation snippets and code examples.
+1. **Resolve the library ID.** Call `resolve-library-id` with the library name and what to look up in the library's documentation. The tool returns matching libraries with their Context7 IDs (`/org/project` format), descriptions, snippet counts, and quality scores. Pick the best match — prioritize official sources, name match, and high benchmark scores.
+2. **Query the docs.** Call `query-docs` with the chosen library ID and what to look up in the library's documentation, scoped to a single concept — if the question spans multiple distinct concepts, make a separate call per concept with the same library ID, unless the question is about how the concepts interact. The tool returns documentation snippets and code examples.
 3. **Answer.** Cite the library ID you used and quote code examples verbatim when relevant.
 
 If the user supplies a library ID in `/org/project` or `/org/project/version` format directly, skip step 1 and call `query-docs` immediately.

packages/tools-ai-sdk/src/prompts/system.ts

@@ -34,9 +34,9 @@ Step 2: Analyze the results from resolveLibraryId and select the BEST library ID
    - 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
+Step 3: Call 'queryDocs' with the selected library ID and what to look up in the library's documentation
    - Use the exact library ID from the resolveLibraryId results
-   - Include the user's original question as the query parameter
+   - Pass what to look up in the library's documentation as the query parameter
 
 Step 4: Provide a clear answer with code examples from the documentation
 

packages/tools-ai-sdk/src/tools/query-docs.ts

@@ -45,7 +45,7 @@ export function queryDocs(config: Context7ToolsConfig = {}) {
       query: z
         .string()
         .describe(
-          "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."
+          "What to look up in the library's documentation, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. 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 }: { libraryId: string; query: string }) => {

packages/tools-ai-sdk/src/tools/resolve-library-id.ts

@@ -40,7 +40,7 @@ export function resolveLibraryId(config: Context7ToolsConfig = {}) {
       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."
+          "What to look up in the library's documentation. 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()

plugins/claude/context7/agents/docs-researcher.md

@@ -16,7 +16,7 @@ When given a question about a library or framework, fetch the relevant documenta
 
 2. **Resolve the library ID**: Call `resolve-library-id` with:
    - `libraryName`: The library name (e.g., "react", "next.js", "prisma")
-   - `query`: The user's full question for relevance ranking
+   - `query`: What to look up in the library's documentation for relevance ranking
 
 3. **Select the best match**: From the results, pick the library with:
    - Exact or closest name match
@@ -25,7 +25,7 @@ When given a question about a library or framework, fetch the relevant documenta
 
 4. **Fetch documentation**: Call `query-docs` with:
    - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)
-   - `query`: The user's specific question for targeted results, scoped to a single concept
+   - `query`: What to look up in the library's documentation for targeted results, scoped to a single concept
 
 5. **Return a focused answer**: Summarize the relevant documentation with:
    - Direct answer to the question
@@ -34,7 +34,7 @@ When given a question about a library or framework, fetch the relevant documenta
 
 ## Guidelines
 
-- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept
+- Describe what to look up in the library's documentation in the query parameter, but keep each query to a single concept
 - If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic
 - When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available
 - If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks

plugins/claude/context7/skills/context7-mcp/SKILL.md

@@ -21,7 +21,7 @@ Activate this skill when the user:
 Call `resolve-library-id` with:
 
 - `libraryName`: The library name extracted from the user's question
-- `query`: The user's full question (improves relevance ranking)
+- `query`: What to look up in the library's documentation (improves relevance ranking)
 
 ### Step 2: Select the Best Match
 
@@ -36,7 +36,7 @@ From the resolution results, choose based on:
 Call `query-docs` with:
 
 - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)
-- `query`: The user's specific question, scoped to a single concept
+- `query`: What to look up in the library's documentation, scoped to a single concept
 
 If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.
 
@@ -50,7 +50,7 @@ Incorporate the fetched documentation into your response:
 
 ## Guidelines
 
-- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept
+- **Be specific**: Describe what to look up in the library's documentation, but keep each query to a single concept
 - **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact
 - **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
 - **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks