sort_by_relevance
Sort and rank a list of documents based on their relevance to a specific query. Use this tool to filter and prioritize information for document retrieval or content organization.
Instructions
Rerank a list of documents by relevance to a query using Jina Reranker API. Use this when you have multiple documents and want to sort them by how well they match a specific query or topic. Perfect for document retrieval, content filtering, or finding the most relevant information from a collection.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| documents | Yes | Array of document texts to rerank by relevance | |
| query | Yes | The query or topic to rank documents against (e.g., 'machine learning algorithms', 'climate change solutions') | |
| top_n | No | Maximum number of top results to return |
Implementation Reference
- src/tools/jina-tools.ts:545-597 (handler)The handler function that executes the tool logic: validates input, checks API token, calls Jina Reranker API at https://api.jina.ai/v1/rerank with model 'jina-reranker-v2-base-multilingual', processes response, and returns ranked documents as YAML-formatted text items.async ({ query, documents, top_n }: { query: string; documents: string[]; top_n?: number }) => { try { const props = getProps(); const tokenError = checkBearerToken(props.bearerToken); if (tokenError) { return tokenError; } if (documents.length === 0) { throw new Error("No documents provided for reranking"); } const response = await fetch('https://api.jina.ai/v1/rerank', { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${props.bearerToken}`, }, body: JSON.stringify({ model: 'jina-reranker-v2-base-multilingual', query, top_n: top_n || documents.length, documents }), }); if (!response.ok) { return handleApiError(response, "Document reranking"); } const data = await response.json() as any; // Return each result as individual text items for consistency const contentItems: Array<{ type: 'text'; text: string }> = []; if (data.results && Array.isArray(data.results)) { for (const result of data.results) { contentItems.push({ type: "text" as const, text: yamlStringify(result), }); } } return { content: contentItems, }; } catch (error) { return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`); } },
- src/tools/jina-tools.ts:541-543 (schema)Zod schema defining inputs: query (string), documents (array of strings), optional top_n (number). Used for input validation in the tool registration.query: z.string().describe("The query or topic to rank documents against (e.g., 'machine learning algorithms', 'climate change solutions')"), documents: z.array(z.string()).describe("Array of document texts to rerank by relevance"), top_n: z.number().optional().describe("Maximum number of top results to return")
- src/tools/jina-tools.ts:537-597 (registration)Registers the 'sort_by_relevance' tool on the MCP server within the registerJinaTools function, including name, description, schema, and handler.server.tool( "sort_by_relevance", "Rerank a list of documents by relevance to a query using Jina Reranker API. Use this when you have multiple documents and want to sort them by how well they match a specific query or topic. Perfect for document retrieval, content filtering, or finding the most relevant information from a collection.", { query: z.string().describe("The query or topic to rank documents against (e.g., 'machine learning algorithms', 'climate change solutions')"), documents: z.array(z.string()).describe("Array of document texts to rerank by relevance"), top_n: z.number().optional().describe("Maximum number of top results to return") }, async ({ query, documents, top_n }: { query: string; documents: string[]; top_n?: number }) => { try { const props = getProps(); const tokenError = checkBearerToken(props.bearerToken); if (tokenError) { return tokenError; } if (documents.length === 0) { throw new Error("No documents provided for reranking"); } const response = await fetch('https://api.jina.ai/v1/rerank', { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${props.bearerToken}`, }, body: JSON.stringify({ model: 'jina-reranker-v2-base-multilingual', query, top_n: top_n || documents.length, documents }), }); if (!response.ok) { return handleApiError(response, "Document reranking"); } const data = await response.json() as any; // Return each result as individual text items for consistency const contentItems: Array<{ type: 'text'; text: string }> = []; if (data.results && Array.isArray(data.results)) { for (const result of data.results) { contentItems.push({ type: "text" as const, text: yamlStringify(result), }); } } return { content: contentItems, }; } catch (error) { return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`); } },
- src/index.ts:20-21 (registration)Calls registerJinaTools(server, getProps) in the MCP agent's init method, which registers the sort_by_relevance tool among others.// Register all Jina AI tools registerJinaTools(this.server, () => this.props);