Tool Resolution

Self-correcting tool name resolution with suggestions and opt-in strict mode

Typo a tool name and PraisonAI tells you what you meant — and, with strict mode on, refuses to start until you fix it.

from praisonaiagents import Agent

Agent(name="Search", instructions="Search the web", tools=["internet_serch"])
# WARNING  Unknown tool 'internet_serch'. Did you mean 'internet_search'? Run 'praisonai tools list'.

Quick Start

1. Get a suggestion

   from praisonaiagents import Agent
   
   Agent(name="Assistant", instructions="Search the web", tools=["web_serch"])
   # WARNING  Unknown tool 'web_serch'. Did you mean 'web_search'? Run 'praisonai tools list'.

2. Fail fast in CI

   export PRAISONAI_STRICT_TOOLS=true
   python my_agent.py   # raises ToolResolutionError on any typo

3. Route suggestions yourself

   from praisonaiagents.tools import resolve_tool_names
   
   def my_reporter(unknown, suggestions):
       for name in unknown:
           print(f"Skipping unknown tool {name}; try {suggestions[name]}")
   
   tools = resolve_tool_names(["web_serch"], on_unknown=my_reporter)

How It Works

Every tool name passes through resolve_tool_names, which looks it up, and on a miss computes the closest known names.

The suggestion catalogue is the union of the registry (get_registry().list_tools()), the built-in TOOL_MAPPINGS keys, and praisonai_tools.__all__ when the extra is installed.

Agent.__init__ routes a list/tuple tools= through the per-element resolver, so name strings resolve regardless of whether callables are also present.

Accepted tool shapes

A tools=[...] element can now be a plain function, a callable class instance, or a BaseTool-style instance.

BaseTool-style instances — anything exposing a .name attribute and a .run method, such as ClarifyTool — are accepted alongside plain functions and callable classes. When a callable tool also carries a .name attribute, .name wins over __name__.

from praisonaiagents import Agent

class ClarifyTool:
    name = "clarify"
    def run(self, question: str) -> str:
        return f"Please clarify: {question}"

Agent(name="Helper", instructions="Ask before acting", tools=[ClarifyTool()])

Mixed tools lists

One tools=[...] list can freely mix callables and tool-name strings.

from praisonaiagents import Agent

def my_tool(x: str) -> str:
    """A local tool."""
    return "local:" + x

# Callable + built-in name string in the same list — both work.
agent = Agent(
    name="Assistant",
    instructions="Use the local tool and read files",
    tools=[my_tool, "read_file"],
)
agent.start("Read config.json and process it")

Previously, adding a single callable to a list of names silently left every name unresolved; each name is now resolved individually.

Unknown names inside a mixed list behave exactly like an all-strings list — warned and suggested by default, or raised under strict mode.

from praisonaiagents import Agent

def my_tool(x: str) -> str:
    return x

# 'no_such_tool' is unknown → warned + suggested (or raised under strict mode),
# my_tool is kept. Same contract as tools=["no_such_tool"].
Agent(name="Assistant", instructions="x", tools=[my_tool, "no_such_tool"])
# WARNING  Unknown tool 'no_such_tool'. ... Run 'praisonai tools list'.

Resolve a mixed list yourself

Call resolve_tools_list() to resolve a possibly-mixed list without building an agent.

from praisonaiagents.tools.resolver import resolve_tools_list

def my_tool(x: str) -> str:
    return x

# Non-string entries keep their position; name strings resolve.
tools = resolve_tools_list([my_tool, "read_file"])
# strict=True raises ToolResolutionError on any unknown name; on_unknown routes suggestions.

resolve_tool_names() is unchanged and now delegates to resolve_tools_list(), so existing code is unaffected.

Choosing a Mode

Pick the behaviour that matches where your agent runs.

Configuring Strict Mode

Turn strict mode on with an environment variable, a keyword argument, or a callback.

export PRAISONAI_STRICT_TOOLS=true   # 1 / true / yes (case-insensitive)

from praisonaiagents.tools import resolve_tool_names

resolve_tool_names(["web_serch"], strict=True)   # raises ToolResolutionError

from praisonaiagents.tools import resolve_tool_names

def _on_unknown(unknown, suggestions):
    raise SystemExit(f"unknown tools: {unknown}, suggestions: {suggestions}")

resolve_tool_names(["web_serch"], on_unknown=_on_unknown)

The signature reads the environment variable only when strict is left unset:

def resolve_tool_names(
    names: List[str],
    *,
    strict: Optional[bool] = None,
    on_unknown: Optional[Callable[[List[str], Dict[str, List[str]]], None]] = None,
) -> List[Any]:
    ...

The ToolResolutionError Shape

Strict mode raises ToolResolutionError, carrying the unknown names and their suggestions.

from praisonaiagents import Agent
from praisonaiagents.tools import ToolResolutionError

try:
    Agent(tools=["web_serch"])   # with PRAISONAI_STRICT_TOOLS=true
except ToolResolutionError as e:
    print(e.unknown)       # ['web_serch']
    print(e.suggestions)   # {'web_serch': ['web_search']}
    print(str(e))          # "Unknown tool 'web_serch'. Did you mean 'web_search'? Run 'praisonai tools list'."

ToolResolutionError subclasses ValueError, so existing except ValueError: blocks still catch it.

Common Patterns

Break the build on a typo in CI, then keep exploration friendly locally.

# CI entrypoint — fail fast
import os
os.environ["PRAISONAI_STRICT_TOOLS"] = "true"

from praisonaiagents import Agent
Agent(name="CI", instructions="Run checks", tools=["web_search", "read_file"])

Ship suggestions through your own logging or alerting for long-running services.

import logging
from praisonaiagents.tools import resolve_tool_names

log = logging.getLogger("agents")

def report(unknown, suggestions):
    for name in unknown:
        log.error("unknown tool %s — try %s", name, suggestions[name])

resolve_tool_names(["web_serch", "read_fil"], on_unknown=report)

Best Practices

Related