Skip to main content

​
Overview

Context7 provides two AI SDK tools that work together to fetch documentation:
  1. resolveLibraryId - Searches for libraries and returns Context7-compatible library IDs
  2. queryDocs - Fetches documentation for a specific library using its ID

​
resolveLibraryId

Resolves a library name to a Context7-compatible library ID and returns matching libraries.

​
Function Signature

function resolveLibraryId(config?: Context7ToolsConfig): Tool

​
Configuration

interface Context7ToolsConfig {
  /**
   * Context7 API key. If not provided, uses CONTEXT7_API_KEY environment variable.
   */
  apiKey?: string;
}

​
Input Schema

{
  query: string;        // The user's original question or task
  libraryName: string;  // Library name to search for
}

​
Usage Example

import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Find React documentation about hooks',
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(5),
});

​
With Custom API Key

const tool = resolveLibraryId({
  apiKey: 'ctx7sk-...',
});

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Search for Next.js library',
  tools: {
    resolveLibraryId: tool,
  },
  stopWhen: stepCountIs(3),
});

​
Return Format

Returns an array of library objects with:
  • Library ID (e.g., /reactjs/react.dev, /vercel/next.js)
  • Description
  • Source reputation (High/Medium/Low)
  • Code snippet coverage
  • Benchmark score (quality indicator, 100 is highest)

​
Tool Description

The tool uses this description for the AI model:
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)

​
queryDocs

Fetches documentation for a library using its Context7 library ID.

​
Function Signature

function queryDocs(config?: Context7ToolsConfig): Tool

​
Configuration

interface Context7ToolsConfig {
  /**
   * Context7 API key. If not provided, uses CONTEXT7_API_KEY environment variable.
   */
  apiKey?: string;
}

​
Input Schema

{
  libraryId: string;  // Context7-compatible library ID from resolveLibraryId
  query: string;      // Specific question or topic to search for
}

​
Usage Example

import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'How do I use React hooks?',
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(5),
});

​
With streamText

import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
import { streamText, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt: 'Explain Next.js App Router',
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(5),
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

​
Direct Library ID Usage

If you already know the library ID, you can skip resolveLibraryId: 
const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Get documentation about routing from /vercel/next.js',
  tools: {
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(3),
});

​
Tool Description

The tool uses this description for the AI model:
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.

​
Multi-Step Workflow

Both tools work together in a typical workflow: 
import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text, steps } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'How do I implement server actions in Next.js?',
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(5),
});

// The model will:
// Step 1: Call resolveLibraryId with libraryName: "Next.js"
// Step 2: Call queryDocs with the returned library ID and query about server actions
// Step 3: Synthesize answer with code examples

console.log(text);
console.log('Steps taken:', steps.length);

​
Advanced Configuration

​
Custom API Keys per Tool

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Find React documentation',
  tools: {
    resolveLibraryId: resolveLibraryId({ apiKey: 'ctx7sk-resolve-key' }),
    queryDocs: queryDocs({ apiKey: 'ctx7sk-docs-key' }),
  },
  stopWhen: stepCountIs(5),
});

​
With Additional Tools

import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk';
import { generateText, tool } from 'ai';
import { z } from 'zod';
import { openai } from '@ai-sdk/openai';

const customTool = tool({
  description: 'Search web for additional context',
  inputSchema: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    // Custom implementation
    return { result: 'Custom data' };
  },
});

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Find React docs and web resources',
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
    searchWeb: customTool,
  },
});

​
Error Handling

Both tools handle errors gracefully and return informative messages: 
// If library not found
'No libraries found matching "invalid-lib". Try a different search term or check the library name.'

// If API key is invalid
'Error searching for libraries: Unauthorized. Check your API key and try again.'

// If documentation not found
'No documentation found for library "/invalid/id". This might have happened because you used an invalid Context7-compatible library ID. Use \'resolveLibraryId\' to get a valid ID.'

​
Type Exports

The package re-exports useful types from the SDK: 
import type {
  Context7Config,
  Library,
  Documentation,
  GetContextOptions,
} from '@upstash/context7-tools-ai-sdk';

​
Best Practices

  1. Always use stepCountIs: Prevent infinite loops by setting a maximum step count
  2. Let AI decide workflow: The model will automatically call resolveLibraryId before queryDocs
  3. Use environment variables: Store API keys in CONTEXT7_API_KEY for security
  4. Provide specific queries: More detailed queries yield better documentation results
  5. Handle tool results: Check the steps array to see which tools were called

​
Next Steps

Context7Agent

Use the pre-configured agent that handles the multi-step workflow automatically

Build docs developers (and LLMs) love

Get started for freeTalk to us