Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Description

Tools configuration defines the tools available to an AgenticResearchStep. Each tool requires a name, description, and either step_config (for simple tools) or graph_config (for complex multi-step tools).

​
Tool Definition

Each tool in tools_config requires:
FieldDescription
nameUnique identifier for the tool
descriptionDescription shown to the LLM for tool selection
step_configSingle-step tool configuration
graph_configMulti-step tool configuration (for complex tools)

​
Using step_config (Simple Tools)

For tools that map to a single step: 
tools_config:
  - name: search_docs
    description: Search the document datastore for relevant information.
    step_config:
      type: SearchUnstructuredDataStep
      config:
        top_k: 50
        lexical_alpha: 0.1
        semantic_alpha: 0.9
        reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
        rerank_top_k: 12
        reranker_score_filter_threshold: 0.2

​
Using graph_config (Complex Tools)

For tools that require multiple steps: 
tools_config:
  - name: search_and_summarize
    description: Search documents and summarize the results.
    graph_config:
      version: 0.1
      inputs:
        query: str
      outputs:
        summary: str
      nodes:
        search:
          type: SearchUnstructuredDataStep
          config:
            top_k: 20
          input_mapping:
            query: __inputs__#query
        
        summarize:
          type: LanguageModelStep
          config:
            prompt_template: |
              Summarize these search results for the query "{query}":
              {retrievals}
            model_id: "vertex_ai/gemini-2.0-flash"
          input_mapping:
            query: __inputs__#query
            retrievals: search#retrievals
        
        __outputs__:
          type: output
          input_mapping:
            summary: summarize#response

​
Multiple Tools

You can configure multiple tools for an agent to choose from: 
tools_config:
  - name: search_docs
    description: |
      Search internal documentation. Use for questions about 
      company policies, procedures, and technical guides.
    step_config:
      type: SearchUnstructuredDataStep
      config:
        top_k: 50

  - name: search_web
    description: |
      Search the web for current information. Use for questions
      about external topics, news, or publicly available data.
    step_config:
      type: WebSearchStep
      config:
        model: "gemini-2.5-flash"

  - name: query_database
    description: |
      Query the structured database. Use for questions about
      metrics, statistics, or tabular data.
    step_config:
      type: QueryStructuredDatastoreStep

​
Tool Descriptions Best Practices

Good tool descriptions help the LLM choose the right tool: 
# Good: Specific about when to use
description: |
  Search the HR policy database. Use this tool for questions about:
  - Employee benefits and compensation
  - Time off and leave policies  
  - Performance review processes
  - Hiring and onboarding procedures

# Bad: Too vague
description: Search for HR stuff.
For SearchUnstructuredDataStep tools, these settings provide good baseline performance: 
step_config:
  type: SearchUnstructuredDataStep
  config:
    top_k: 50
    lexical_alpha: 0.1
    semantic_alpha: 0.9
    reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
    rerank_top_k: 12
    reranker_score_filter_threshold: 0.2

​
MCP Tools

You can also configure MCP (Model Context Protocol) server tools: 
tools_config:
  - name: crm_search
    description: Search customer records in the CRM system.
    step_config:
      type: MCPClientStep
      config:
        server_url: "https://mcp-server.example.com"
        tool_name: "search_customers"
        tool_args: '{"query": "$query"}'
        auth_headers:
          Authorization: "Bearer ${CRM_API_TOKEN}"