Implementation:CrewAIInc CrewAI ContextualAI Rerank Tool

Knowledge Sources	CrewAI
Domains	Tools, RAG, ContextualAI
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for reranking documents using Contextual AI's instruction-following reranker provided by CrewAI.

Description

The ContextualAIRerankTool class extends BaseTool to reorder documents based on relevance to a query using Contextual AI's reranking API (https://api.contextual.ai/v1/rerank). The tool accepts a query, a list of document texts, an optional instruction for custom ranking behavior, optional per-document metadata, and a model selection (defaulting to ctxl-rerank-en-v1-instruct). The _run method validates that metadata length matches the documents list if provided, constructs a JSON payload, and sends a POST request with bearer token authentication. Returns JSON with document indices and relevance scores ordered by relevance. The instruction-following capability allows domain-specific ranking criteria beyond simple similarity matching.

Usage

Use this tool when CrewAI agents need to improve retrieval quality in RAG systems by reordering search results based on relevance, recency, authority, or other custom contextual factors.

Code Reference

Source Location

• Repository: CrewAI
• File: lib/crewai-tools/src/crewai_tools/tools/contextualai_rerank_tool/contextual_rerank_tool.py
• Lines: 1-81

Signature

class ContextualAIRerankTool(BaseTool):
    name: str = "Contextual AI Document Reranker"
    description: str = "Rerank documents using Contextual AI's instruction-following reranker"
    args_schema: type[BaseModel] = ContextualAIRerankSchema
    api_key: str

    def _run(self, query: str, documents: list[str],
             instruction: str | None = None, metadata: list[str] | None = None,
             model: str = "ctxl-rerank-en-v1-instruct") -> str: ...

Import

from crewai_tools import ContextualAIRerankTool

I/O Contract

Inputs

Name	Type	Required	Description
api_key	str	Yes	Contextual AI API key (constructor)
query	str	Yes	The search query to rerank documents against
documents	list[str]	Yes	List of document texts to rerank
instruction	str or None	No	Optional instruction for custom reranking behavior
metadata	list[str] or None	No	Optional metadata for each document (must match documents length)
model	str	No	Reranker model to use (default "ctxl-rerank-en-v1-instruct")

Outputs

Name	Type	Description
_run() returns	str	JSON string with document indices and relevance scores ordered by relevance

Usage Examples

Basic Usage

from crewai_tools import ContextualAIRerankTool

tool = ContextualAIRerankTool(api_key="your-api-key")
result = tool.run(
    query="How to deploy machine learning models",
    documents=[
        "Guide to ML model deployment on Kubernetes",
        "Introduction to machine learning basics",
        "Production ML systems architecture"
    ],
    instruction="Prioritize production deployment guides"
)

Related Pages

• Principle:CrewAIInc_CrewAI_Built_In_Tool_Selection