3tears Agent Tools

Tool framework for LLM agents. Provides tool routing, execution, context management, MCP integration, and a set of builtin tools.

Part of the 3tears framework.

ToolServer baseline audit

ToolServer.handle_call stamps every dispatch with a unified AuditEvent envelope (event_type='tool.call') via threetears.agent.audit.publish_audit. The baseline emission fires in a finally block so success, failure (tool returned success=False), and error (tool raised) outcomes all produce a row. Identity axes carry from the active ToolCallScope (actor_user_id, calling_agent_id, owner_agent_id, customer_id, correlation_id); resource_namespace_id / resource_namespace_type stay None at the baseline layer since the tool resolves its target inside execute. Per-tool additive events (e.g. workspace.fs_write) still publish via publish_audit and ride alongside the baseline row under the same correlation_id. The (correlation_id, event_type) partial unique index on platform_audit.audit_events keeps them distinct. Emission is fire-and-forget: NATS publish failures log WARN and never taint the tool's response.

Tool-as-namespace emission

Tool namespace materialization is platform-owned. ToolServer.publish_registration writes the RegistrationManifest (carrying pod_id + tools + the owner_agent_id / customer_id envelope fields), and a platform-side namespace emitter subscribes to {ns}.tools.register and upserts one namespaces row of type tool per tool. This is the sole writer in the platform.

Agent-spun ToolServers stamp agent_id + customer_id on the RegistrationManifest so the emitter lands rows with the right owner scope; platform-built-in pods (admin tool server, datasource tool pod) leave both None and the row lands with NULL owner columns (admitted under the widened namespaces_row_scope_customer_ck carve-out for tool type alongside system / model).

The canonical name shape is tools.<sanitized-mcp>.<sanitized-version> (per build_namespace_name); metadata carries the pre-sanitized natural-identity fields mcp_name / mcp_version / pod_id so downstream pattern matching (platform access materializer agent.yaml access.tools patterns + registry authorizer canonical-name lookup) does not need to reverse the sanitization rules. Deterministic uuid5 derived from (mcp_name, version, owner_agent_id_hex) keeps concurrent emitters race-safe via ON CONFLICT (id) DO UPDATE.

ToolServer holds no NamespaceCollection and has no constructor parameter to take one: register_tool / deregister_tool publish the manifest and nothing else. The pod-side emitter that once wrote and deleted these rows is deleted -- its write could not land (the agent's L3 proxy resolves platform-scoped writes to the per-agent agent_<hex> schema, which has no namespaces table) and its delete raised on every call (it passed a bare UUID to a Collection keyed on the composite (row_scope, namespace_id)). packages/agent/tools/tests/enforcement/test_no_agent_side_namespace_writes.py fails a build that brings any of it back.

Installation

pip install 3tears-agent-tools

# Optional extras for builtin tools
pip install "3tears-agent-tools[calculator]"   # simpleeval
pip install "3tears-agent-tools[units]"        # pint
pip install "3tears-agent-tools[fetch]"        # trafilatura
pip install "3tears-agent-tools[document]"     # PyMuPDF, python-docx, openpyxl
pip install "3tears-agent-tools[all]"          # everything

Components

ToolRouter

Routes user messages to the appropriate tool using a lightweight LLM call. Includes recall-intent detection to avoid re-invoking tools when users ask about previous results.

from threetears.agent.tools import ToolRouter, is_recall_intent

# Quick check -- no LLM call needed
if is_recall_intent("show me what the calculator said"):
    # User wants to recall, not invoke

# Full routing with LLM
router = ToolRouter(chat_model)
decision = await router.route(user_message, tool_descriptions)
# decision.tool_name, decision.reasoning

ToolExecutor

Invokes a tool-LLM: sends the user message to a secondary model configured for a specific task.

from threetears.agent.tools import ToolExecutor

executor = ToolExecutor()
result = await executor.invoke_with_tools(
    chat_model=tool_model,
    user_message="What is 42 * 17?",
    tools=[calculator_tool],
    tool_name="calculator",
)
# result.content, result.tool_calls

ToolContextManager

Tracks tool invocations and results across a conversation for recall support.

from threetears.agent.tools import ToolContextManager

ctx = ToolContextManager()
await ctx.record_invocation("calculator", "42 * 17", "714")
await ctx.get_recall_context("calculator")  # Returns formatted recall string

McpClient

MCP (Model Context Protocol) integration for connecting to external tool servers.

from threetears.agent.tools import McpClient

async with McpClient(server_config) as client:
    tools = await client.list_tools()
    result = await client.invoke_tool("tool_name", {"param": "value"})

Builtin Tools

Register all builtin tools at once:

from threetears.agent.tools import register_builtins, ToolRegistry

registry = ToolRegistry()
register_builtins(registry)
# Registers: calculator, unit_converter, dice_roller, date_time,
#            random_number, web_fetch, text_transform, parse_document

Todo Tools

Todo list management behind a storage protocol:

from threetears.agent.tools import TodoStorage, load_todo_tools_from_storage

class MyTodoStorage(TodoStorage):
    async def add(self, conv_id, user_id, title, list_name, msg_id) -> dict: ...
    async def list_all(self, conv_id) -> list[dict]: ...
    # ... other methods

tools = load_todo_tools_from_storage(my_storage, snapshot_callback=on_snapshot)

Protocols

For media-related capabilities, implement these protocols:

from threetears.agent.tools import (
    ImageGenerationBackend,
    MediaStorage,
    VisionProvider,
    TranscriptionProvider,
)

Document Parsing

Parse PDF, DOCX, XLSX, and plain text with optional OCR:

from threetears.agent.tools import parse_document, OcrConfig

result = await parse_document(
    file_bytes=data,
    filename="report.pdf",
    ocr_config=OcrConfig(enabled=True),
)
# result.sections -- list of DocumentSection with title, content, page numbers

Project links

Data verified by PyPI on Sep 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.41.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pace from gravatar.com pace

Credits

Author: pace

GitHub Statistics

Data verified by PyPI on Sep 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

all calculator document docx fetch ocr pdf units vision xlsx

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

3tears_agent_tools-0.36.0.tar.gz (433.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

3tears_agent_tools-0.36.0-py3-none-any.whl (285.2 kB view details)

Uploaded Python 3

File details

Details for the file 3tears_agent_tools-0.36.0.tar.gz.

File metadata

  • Download URL: 3tears_agent_tools-0.36.0.tar.gz
  • Upload date:
  • Size: 433.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for 3tears_agent_tools-0.36.0.tar.gz
Algorithm Hash digest
SHA256 013c3d561708ffc02db979bac0455842d280600940e4c093c9d0473e2d23f924
MD5 4925196fd5aea87fc083cb7fa6cc90c3
BLAKE2b-256 a30a6edd9c6c280e7b67a01b822ba28bbb7bbbaa1cf66e2ed493d7a505e0d5d7

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_tools-0.36.0.tar.gz:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file 3tears_agent_tools-0.36.0-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_agent_tools-0.36.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1d984af9720d35804a3a58dc5d813e72e676738dc2ce094982b77d92ece6e823
MD5 3ee46eb1088abf978c6d299dacd5de79
BLAKE2b-256 152e6df39278f5ba945976ecaa1c9e0c9cd3f31abb123c3950a73ec88e286bbe

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_tools-0.36.0-py3-none-any.whl:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.41.4

2 files

0.41.3

2 files

0.41.2

2 files

0.41.1

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

This release

0.36.0 This release

2 files

0.35.1

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.1

2 files

0.32.0

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

0.26.1

2 files

0.26.0

2 files

0.25.0

2 files

0.24.7

2 files

0.24.6

2 files

0.24.5

2 files

0.24.4

2 files

0.24.3

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.11

2 files

0.23.10

2 files

0.23.9

2 files

0.23.8

2 files

0.23.7

2 files

0.23.6

2 files

0.23.5

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.4

2 files

0.19.3

2 files

0.19.2

2 files

0.19.1

2 files

0.19.0

2 files

0.18.0

2 files

0.17.9

2 files

0.17.8

2 files

0.17.7

2 files

0.17.6

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page