Skip to content

Add A Tool

The smallest public builder path is to add a custom tool using brain.patterns.

Minimal Example

See examples/custom_tool/README.md.

Core pattern:

from brain.patterns import ReActAgent
from brain.patterns.tools import tool
from brain.providers import LocalEchoProvider

@tool("Return the current status for a named project")
def project_status(project: str) -> str:
    return f"{project} is healthy."

agent = ReActAgent(
    provider=LocalEchoProvider(),
    tools={"project_status": project_status},
)

Design Rules

  1. Keep the function small and explicit.
  2. Make side effects obvious in the tool description.
  3. Prefer deterministic return values in examples and tests.
  4. Add one runnable example and one focused test.

When To Use A Heavier Tool Surface

Use the runtime or MCP tool layers only when you need:

  • approval and policy coupling
  • broader CLI/runtime integration
  • connector-backed capabilities

For public 0.3.0, start with the simpler brain.patterns builder path unless you specifically need the heavier runtime integration.