toollint

Lint tool definitions for AI agents. Checks descriptions, parameter docs, and semantic overlap so models pick the right tool.

Install

pip install toollint
# With semantic overlap detection:
pip install toollint[semantic]

Requires Python >= 3.10.

Quick start

toollint --src ./src/             # scan + lint in one command
toollint build --src ./src/       # just collect, write _build/tools.json
toollint check                    # lint _build/tools.json
toollint check --format json      # CI-friendly output
toollint check --quiet            # no output on clean runs
cat tools.json | toollint check --stdin  # read from pipe

Defining tools

Three ways to define tools. Mix and match.

Option A: @tool decorator

from toollint import tool

@tool
def search_web(query: str, max_results: int = 10) -> str:
    """Search the web for current information.

    Args:
        query: The search query string.
        max_results: Maximum number of results.
    """
    ...

# Override name and description via decorator kwargs
@tool(name="web_search", description="Search the internet")
def search(query: str) -> str:
    ...

# Async functions work too
@tool
async def fetch_data(url: str) -> dict:
    """Fetch data from a URL.

    Args:
        url: The URL to fetch.
    """
    ...

The @tool decorator is an identity function at runtime — zero overhead. The AST scanner finds it statically. Only matches @tool imported from toollint; from otherlib import tool is ignored.

Docstrings are parsed in Google, Sphinx, and NumPy styles. First match wins.

Option B: Tool base class

from toollint import Tool

class SearchDocs(Tool):
    name = "search_docs"
    description = "Search documentation for a query string"

    def run(self, query: str, max_results: int = 10) -> str:
        """Run the search.

        Args:
            query: The search query.
            max_results: Maximum results.
        """
        ...

# with type annotations preserved
from typing import Optional, Literal

class CreateFile(Tool):
    name = "create_file"
    description = "Create a new file with the given content"

    def run(self, path: str, content: str, mode: Literal["write", "append"] = "write") -> str:
        """Create a file.

        Args:
            path: File path.
            content: File content.
            mode: Write mode.
        """
        ...

The AST scanner finds classes inheriting from toollint.Tool. Extracts name and description class attributes, then run() method signature for parameters. self is automatically excluded from the parameter list.

Only matches Tool imported from toollint. from otherlib import Tool is ignored.

Option C: tools/*.json

{
  "name": "extra_tool",
  "description": "An extra tool from JSON config",
  "parameters": [
    {
      "name": "query",
      "type": "str",
      "description": "The search query",
      "required": true
    }
  ]
}

Hand-written JSON definitions. Files can be a JSON array or NDJSON (one object per line). All *.json files in tools/ are merged at build time. Duplicate names: last file wins with a warning.

Public API

Everything importable from toollint root. Internal modules start with _ — not part of the public contract.

Classes

ToolDef

A complete tool definition. The central data structure.

from toollint import ToolDef, ParameterDef

tool = ToolDef(
    name="search_web",
    description="Search the web for current information",
    source_file="src/search.py",
    source_line=42,
    parameters=[
        ParameterDef(
            name="query",
            type="str",
            description="The search query string",
            required=True,
        ),
        ParameterDef(
            name="max_results",
            type="int",
            required=False,
        ),
    ],
)

ParameterDef

A parameter within a tool definition.

from toollint import ParameterDef

param = ParameterDef(
    name="query",
    type="str",
    description="The search query",
    required=True,
    parameters=[],  # nested params, e.g. for object/dict types
)

Report

Result of running checks. Returned by scan().

from toollint import scan, ToolDef

tools = [ToolDef(name="a", description="..."), ToolDef(name="b", description="...")]
report = scan(tools)

print(report.ok)       # bool: True if no errors
print(report.errors)   # list[Finding]: error-level findings
print(report.warnings) # list[Finding]: warning-level findings
print(report.skipped)  # list[str]: skipped check names

Finding

A single lint issue. Returned in report.errors and report.warnings.

finding = report.errors[0]
finding.check     # str:   check name, e.g. "duplicate_names"
finding.severity  # Severity enum: ERROR or WARNING
finding.message   # str:   human-readable description
finding.tools     # list[str]: tool names involved
finding.files     # list[str]: source files involved

Decorators and base classes

tool

Runtime no-op decorator. AST scanner finds it statically.

from toollint import tool

@tool
def my_tool(x: str) -> str:
    """Description here.

    Args:
        x: The parameter.
    """
    ...

@tool(name="custom_name", description="Override everything")
def other(y: int) -> str:
    ...

Tool

Abstract base class. Subclass and set name + description class attributes.

from toollint import Tool

class MyTool(Tool):
    name = "my_tool"
    description = "What this tool does"

    def run(self, input: str) -> str:
        ...

Functions

scan(tools, threshold=0.85) -> Report

Run all checks on a list of ToolDef objects. Returns a Report.

from toollint import scan, ToolDef

tools = [
    ToolDef(name="a", description="Search the web for info"),
    ToolDef(name="b", description="Look up things on the internet"),
]
report = scan(tools)

if not report.ok:
    for finding in report.errors:
        print(f"ERROR: {finding.message}")

tools_from_json(path) -> list[ToolDef]

Load tool definitions from a JSON file. Handles both JSON arrays and NDJSON.

from toollint import tools_from_json
from pathlib import Path

tools = tools_from_json(Path("_build/tools.json"))

Severity

from toollint._engine._checks import Severity

Severity.ERROR    # "error"
Severity.WARNING  # "warning"

Import from toollint._engine._checks — intentionally internal. Consumers read finding.severity on the Finding object, don't construct Severity values directly.

Checks

Semantic overlap requires pip install toollint[semantic]. All other checks run with zero ML dependencies.

CLI reference

toollint --src ./src/              build + check (default)
toollint build --src ./src/        collect tools, write _build/tools.json
toollint check                     lint _build/tools.json
toollint check tools.json          lint a specific file
toollint check --stdin             read JSON array or NDJSON from pipe

Exit codes: 0 = clean or warnings only, 1 = errors found, 2 = configuration error.

CI integration

# .github/workflows/toollint.yml
name: toollint
on: [push, pull_request]
jobs:
  lint-tools:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install toollint[semantic]
      - run: toollint --src ./src/

Pre-commit hook:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: toollint
      name: toollint
      entry: toollint
      language: system
      pass_filenames: false

License

Apache-2.0