Tools

Tools are how agents act on the world. @maniac-ai/agents provides a typed tool() helper, abstract BaseToolset / concrete StaticToolset, MCP integration, and delegation wrappers that spawn nested agent runs.

Topics

• Defining tools — tool(), BaseToolset, StaticToolset
• Builtin tools — bg_*, remember, set_plan
• MCP and delegation — MCPToolset, asDelegated()

How tools reach the model

flowchart TD
  Agent["Agent spec"] --> Collect["Collect tools + toolsets"]
  Collect --> LM["Model sees ToolDef[]"]
  LM -->|"tool_calls"| Invoke["tool.invoke(args)"]
  Invoke --> Result["ToolResult → tool message"]

Inline tools and expanded toolsets merge into the LM's tool surface. The runner validates arguments, runs middleware/guardrails, and appends tool role messages before the next LM iteration.