Toolkits

A Toolkit is a small API wearing sensible shoes for both Python and agents.

1. Motivation

It is easy to wrap the same function once for Python, again for MCP, and a third time for a model provider. The wrappers then disagree about names, schemas, serializers, persistence, and authorization. HeavenBase uses three composable values:

Capsule owns the executable manifest and restore contract.
Tool owns one public tool name, schema, execution Capsule, and serializer.
Toolkit owns an ordered set of Tools plus persistence and export behavior.

Concrete persistence belongs to one explicit application workspace. That keeps Toolkit rows, referenced Capsule rows, Context authority, and cleanup together.

2. Build Function-Like Tools

import heavenbase as hb


@hb.Tool
def add(left: int, right: int) -> int:
    """Add two integers."""
    return left + right


@hb.Tool(name="times")
def multiply(left: int, right: int) -> int:
    """Multiply two integers."""
    return left * right


assert add(left=2, right=3) == 5
assert multiply(left=2, right=3) == 6

Tool accepts a plain callable, an existing Capsule, or decorator options. It keeps the wrapped signature for local calls while exposing JSON-compatible tool schemas for agent boundaries. The default serializer produces compact JSTR output. Set a custom callable or Capsule only when one tool needs a different text boundary.

3. Compose a Toolkit

toolkit = hb.Toolkit(
    "math",
    {
        "add": add,
        "multiply": multiply,
    },
    namespace="demo",
    version="1",
)

assert toolkit.run("add", left=2, right=3) == 5
assert toolkit.run_to_str("multiply", left=2, right=3) == "6"

Toolkit accepts a list, (name, item) pairs, a mapping, Capsules, Tools, or callables. add(...), add_many(...), and @toolkit.tool(...) all normalize items into the same Tool contract. run(...) returns the raw Python value. run_to_str(...) passes that value through the Tool serializer used by MCP and agent clients.

4. Persist in an Explicit Workspace

ws = hb.HeavenBase("math-app", preset="debug")

toolkit_id = toolkit.register(ws=ws)
row = ws.get(toolkit_id, entity=hb.Toolkit)

print(row["name"])
print(row["capsule_refs"])

register(ws=...) stores one sys-toolkit row and the main plus serializer sys-capsule rows referenced by every Tool. It defaults to overwrite mode for same-id content; use on_conflict="raise" or "skip" when conflict policy must be explicit. Omitting ws= uses existing-only hb.HeavenBase.load(). It never creates a default workspace or a process-global Toolkit store.

5. Load, List, Describe, and Delete

loaded = hb.Toolkit.load(
    name="math",
    namespace="demo",
    version="1",
    ws=ws,
)

assert loaded.run("add", left=2, right=3) == 5

rows = hb.Toolkit.list(ws=ws, namespace="demo")
detail = hb.Toolkit.describe(toolkit_id, ws=ws)
removed = hb.Toolkit.delete(toolkit_id, ws=ws)

Loading restores referenced Capsules lazily. delete(...) writes a tombstone by default. Deleting a Toolkit row does not automatically delete Capsule rows that another Toolkit may reference. Versions are explicit strings. Use a new version for a changed public tool contract and select it deliberately when reproducibility matters.

6. Export a FastMCP Server

from fastmcp import Client

server = loaded.to_fastmcp()

async with Client(server) as client:
    tools = await client.list_tools()
    result = await client.call_tool(
        "add",
        {"left": 2, "right": 3},
    )

Use to_mcp_json(...) to print client configuration and serve(...) to run a transport. Keep network servers on loopback unless another trusted layer supplies authentication and transport security. Toolkit.from_fastmcp(...) creates a runtime client Toolkit over a live server. Runtime proxy Tools cannot be persisted because they close over the server handle rather than a durable function.

7. Turn a Workspace into a Scoped Toolkit

workspace_tools = ws.to_mcp(profile="agent")

print(workspace_tools.list_tools())

Workspace Toolkits assemble registered Toolkit families through an MCP profile. A profile scopes exact tools, entities, Skills, and one serializer. Optional domain families activate only through their declared workspace requirements. The bundled profiles include:

Profile	Intended scope
`agent`	Curated schema, read, write, query, explain, and Skill surface
`full`	Trusted administration across all available workspace tools
`memory`	Memory note retrieval and curation
`memstate`	Versioned key-path memory operations
`database`	Database inspection and controlled SQL helpers

Runtime workspace Toolkits are not persistable because their functions close over one live workspace. Persist the underlying profile and Toolkit-family definitions as Registry module records instead.

8. Publish External Toolkit Families

An external module can declare:

toolkit_family with a durable builder target and exact tool names
mcp_profile with tools, entities, Skills, serializer, dependencies, and optional extends
mcp_serializer when the bundled serializers do not fit

The workspace’s Context resolves those records before assembly. Keep every public tool namespaced, validate that the builder output matches the declared inventory, and reject collisions instead of relying on import order. See the GlossWise case study for a module that contributes one domain family plus read, local-file, and curator profiles.

9. Keep the Agent Boundary Narrow

A Tool runs Capsule code with the authority of its server process. Review the callable, schema, serializer, profile scope, and input validation before exposing it.

Prefer the smallest profile that supports the task.
Use keyword-only agent/MCP dispatch and validate untrusted inputs.
Keep filesystem, network, credential, and destructive authority explicit.
Treat full as trusted administration.
Keep application logic in a workspace API; let Tool functions remain thin adapters.
Test the exact exported schema and a real list/call round trip.

Summary

Tools normalize callables and Capsules behind one function-like contract.
Persisted Toolkits and referenced Capsules belong to an explicit application workspace.
Profiles and serializers keep Agent authority narrow and inspectable.

Further Exploration

Related resources:

Capsules - Inspect the executable payload behind a Tool
MCP Toolkit - Review methods, profiles, and serving
HeavenBase MCP - Configure a workspace server
Extensions - Publish Toolkit families and profiles
Building GlossWise - See an external domain Toolkit

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Build Function-Like Tools

3. Compose a Toolkit

4. Persist in an Explicit Workspace

5. Load, List, Describe, and Delete

6. Export a FastMCP Server

7. Turn a Workspace into a Scoped Toolkit

8. Publish External Toolkit Families

9. Keep the Agent Boundary Narrow

Summary

Further Exploration

​1. Motivation

​2. Build Function-Like Tools

​3. Compose a Toolkit

​4. Persist in an Explicit Workspace

​5. Load, List, Describe, and Delete

​6. Export a FastMCP Server

​7. Turn a Workspace into a Scoped Toolkit

​8. Publish External Toolkit Families

​9. Keep the Agent Boundary Narrow

​Summary

​Further Exploration

1. Motivation

2. Build Function-Like Tools

3. Compose a Toolkit

4. Persist in an Explicit Workspace

5. Load, List, Describe, and Delete

6. Export a FastMCP Server

7. Turn a Workspace into a Scoped Toolkit

8. Publish External Toolkit Families

9. Keep the Agent Boundary Narrow

Summary

Further Exploration