Ragex.Agent.ToolSchema (Ragex v0.14.0)

View Source

Converts MCP tool definitions to AI provider tool formats.

Supports:

  • OpenAI function calling format (also used by DeepSeek R1 and Ollama)
  • Anthropic tool use format

Tool sets

Three tool sets are available:

  • All tools (to_openai_tools/0, to_anthropic_tools/0) — every tool defined in the MCP server.
  • Agent tools (agent_tools/1, tools_for_provider/2) — curated subset suitable for autonomous agent analysis. Includes analysis, quality, search, dependency, impact, suggestion, and graph-algorithm tools.
  • RAG query tools (rag_query_tools/1) — read-only subset that reads existing knowledge-graph and embedding data without triggering any heavy analysis pipeline. Used during report generation so the AI can look up code-level evidence without re-running static analysis.

Usage

# Get all tools in OpenAI format
tools = ToolSchema.to_openai_tools()

# Get curated agent tools
tools = ToolSchema.agent_tools(:openai)

# Get read-only RAG query tools for report generation
tools = ToolSchema.rag_query_tools(:anthropic)

# Lookup specific tool
{:ok, tool} = ToolSchema.tool_by_name("semantic_search")

Summary

Functions

agent_tool_names()

Get list of agent tool names.

agent_tools(format \\ :openai)

Get curated subset of tools for agent use.

rag_query_tools(provider \\ :openai)

Get read-only RAG query tools for a provider.

rag_tool_names()

Get read-only RAG query tool names.

to_anthropic_tools()

Get all MCP tools converted to Anthropic tool format.

to_openai_tools()

Get all MCP tools converted to OpenAI function calling format.

tool_by_name(name, format \\ :mcp)

Lookup a tool definition by name.

tools_by_names(names, format \\ :openai)

Convert a list of tool names to their definitions.

tools_for_provider(provider, opts \\ [])

Get tools for a specific provider by name.

Functions

agent_tool_names()

@spec agent_tool_names() :: [String.t()]

Get list of agent tool names.

agent_tools(format \\ :openai)

@spec agent_tools(atom()) :: [map()]

Get curated subset of tools for agent use.

Parameters

  • format - Output format: :openai (default, also for DeepSeek) or :anthropic

Returns

List of tool definitions in the requested format.

rag_query_tools(provider \\ :openai)

@spec rag_query_tools(atom()) :: [map()]

Get read-only RAG query tools for a provider.

Same as tools_for_provider/2 restricted to @rag_tool_names. Useful for report generation where the AI should retrieve context but not re-run the full analysis pipeline.

rag_tool_names()

@spec rag_tool_names() :: [String.t()]

Get read-only RAG query tool names.

These tools read from the existing knowledge graph and embeddings without triggering any heavy analysis pipeline.

to_anthropic_tools()

@spec to_anthropic_tools() :: [map()]

Get all MCP tools converted to Anthropic tool format.

Returns

List of tool definitions in Anthropic format:

[
  %{
    name: "tool_name",
    description: "Tool description",
    input_schema: %{...json_schema...}
  }
]

to_openai_tools()

@spec to_openai_tools() :: [map()]

Get all MCP tools converted to OpenAI function calling format.

This format is also compatible with DeepSeek R1.

Returns

List of tool definitions in OpenAI format:

[
  %{
    type: "function",
    function: %{
      name: "tool_name",
      description: "Tool description",
      parameters: %{...json_schema...}
    }
  }
]

tool_by_name(name, format \\ :mcp)

@spec tool_by_name(String.t(), atom()) :: {:ok, map()} | {:error, :not_found}

Lookup a tool definition by name.

Parameters

  • name - Tool name as string
  • format - Output format: :openai, :anthropic, or :mcp (default)

Returns

  • {:ok, tool} - Tool definition in requested format
  • {:error, :not_found} - Tool not found

tools_by_names(names, format \\ :openai)

@spec tools_by_names([String.t()], atom()) :: [map()]

Convert a list of tool names to their definitions.

Parameters

  • names - List of tool names
  • format - Output format

Returns

List of tool definitions (skips unknown tools).

tools_for_provider(provider, opts \\ [])

@spec tools_for_provider(
  atom(),
  keyword()
) :: [map()]

Get tools for a specific provider by name.

Parameters

  • provider - Provider atom: :deepseek_r1, :openai, :anthropic, :ollama
  • opts - Options:
    • :only - List of tool names to include (default: all agent tools)
    • :except - List of tool names to exclude

Returns

List of tool definitions in the appropriate format for the provider.