Tools

Tools are the actions the LLM can take. Every tool call is executed by Mango and the result is fed back to the LLM.

Built-in tools

from mango.tools import build_mongo_tools
from mango.tools.base import ToolRegistry

tools = ToolRegistry()
for tool in build_mongo_tools(db):
    tools.register(tool)

Available tools

Tool	Description
`list_collections`	List all collections. For databases with 100+ collections, returns a grouped view by name pattern.
`search_collections`	Search collection names by glob pattern (`order`, `_log`).
`describe_collection`	Return schema, indexes and sample documents for a single collection.
`collection_stats`	Document count and storage size for a collection.
`run_mql`	Execute a read-only query: `find`, `aggregate`, `count`, `distinct`.
`search_saved_correct_tool_uses`	Search memory for similar past interactions (used automatically).
`save_text_memory`	Save free-form knowledge about the database.

`run_mql` in detail

This is the main query tool. The LLM constructs a QueryRequest and passes it as JSON arguments:

# find — filter + projection + sort + limit
run_mql(
    operation="find",
    collection="orders",
    filter={"status": "delivered"},
    projection={"_id": 0, "order_id": 1, "total": 1},
    sort={"created_at": -1},
    limit=20,
)

# aggregate — full pipeline
run_mql(
    operation="aggregate",
    collection="orders",
    pipeline=[
        {"$match": {"created_at": {"$gte": "2026-01-01"}}},
        {"$group": {"_id": "$user_id", "total": {"$sum": "$amount"}}},
        {"$sort": {"total": -1}},
        {"$limit": 10},
    ],
)

# count
run_mql(operation="count", collection="users", filter={"active": True})

# distinct
run_mql(operation="distinct", collection="orders", distinct_field="status")

Allowed operations: find, aggregate, count, distinct. Everything else is rejected.

ToolResult

Every tool returns a ToolResult:

@dataclass
class ToolResult:
    success: bool
    data: Any           # the actual result data
    error: str | None   # error message if success=False

    def as_text(self) -> str:
        """Serialize result to text for the LLM."""

ToolRegistry

The registry manages tool lookup and execution:

from mango.tools.base import ToolRegistry

tools = ToolRegistry()

# Register a tool
tools.register(my_tool)

# Get all tool definitions (for the LLM)
definitions = tools.get_definitions()

# Execute a tool by name
result = await tools.execute("run_mql", operation="count", collection="users")

Next step

→ Custom Tools — build your own tools and register them alongside the built-ins.