mcp-toolsmith

mcp-toolsmith audits and compiles Python tool schemas for LLM agents, catching vague names, missing argument descriptions, oversized schemas, overlapping tools, and prompt-injection-like metadata before your agent uses them.

Pre-1.0: JSON tool files and static Python audits are safe by default. Python execution requires --execute and should only be used with trusted code. The public API may change before 1.0.0.

Tool schemas are not just documentation. In MCP, OpenAI-style tool calling, and agent frameworks, names, descriptions, and input schemas shape whether the model chooses the right tool and fills arguments correctly.

Install

pip install mcp-toolsmith

For local development:

python -m pip install -e ".[dev]"

Why?

LLM agents often fail because tool metadata is ambiguous.

Bad tool:

def run(query: str):
    """Run operation."""
    return query

Audit:

mcp-toolsmith audit tools.py --execute --all-public --fail-on warning

Output:

WARNING name.vague: Tool name is too generic for reliable tool selection.
WARNING description.too_short: Tool description is too short to guide model selection.
WARNING schema.arg_description_missing: Argument descriptions are missing for: query.

Usage

Audit a project

Recursively audit supported Python and MCP JSON files:

mcp-toolsmith audit .
mcp-toolsmith audit src/
mcp-toolsmith audit src/tools/

Generated output, virtual environments, dependency directories, and common caches are excluded by default. Add explicit globs when needed:

mcp-toolsmith audit . --exclude "tests/**" --exclude "examples/**"

Store repeatable CI settings in pyproject.toml:

[tool.mcp-toolsmith]
profile = "openai"
fail-on = "warning"
include = ["src/**/*.py"]
exclude = ["tests/**", "examples/**", "src/generated/**"]
ignore = ["schema.description_too_short"]
max-schema-depth = 5

[[tool.mcp-toolsmith.per-file-ignores]]
path = "examples/**"
rules = ["schema.arg_description_missing"]

CLI values override project configuration, which overrides built-in defaults. Suppressions require specific rule codes. Inspect the settings used by the current project with:

mcp-toolsmith config show

Audit JSON tool definitions

JSON tool definitions are safe by default:

mcp-toolsmith audit tools.json

Example JSON input:

{
  "tools": [
    {
      "name": "search_docs",
      "description": "Search project documentation by natural language query.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Question or topic to search for."
          },
          "limit": {
            "type": "integer",
            "description": "Maximum number of results to return.",
            "default": 5
          }
        },
        "required": ["query"]
      }
    }
  ]
}

Example audit output:

OK Audited 1 tool(s) from tools.json
Mode: json
Profile: generic
Errors: 0  Warnings: 0

search_docs [mcp] ~55 schema tokens
  No findings

Compile tools

Compile to MCP-style tool definitions:

mcp-toolsmith compile tools.json --target mcp

Compile to OpenAI-style function definitions:

mcp-toolsmith compile tools.json --target openai

Audit trusted Python files

Python files are parsed statically by default:

mcp-toolsmith audit tools.py

This discovers @tool-decorated functions without executing the file:

from mcp_toolsmith import tool


@tool
def search_docs(query: str, limit: int = 5) -> list[str]:
    """Search project documentation by natural language query.

    Args:
        query: Question or topic to search for.
        limit: Maximum number of results to return.
    """
    return []

Static mode maps common annotations such as str, int, float, bool, dict, and list[str]. Use runtime execution only for trusted files when you need full Pydantic/runtime schema generation:

mcp-toolsmith audit tools.py --execute
mcp-toolsmith compile tools.py --target mcp --execute

Use --execute only for trusted files. In both static and execution modes, default Python discovery only includes functions decorated with @tool.

Use decorator arguments to override the generated tool name or description:

from mcp_toolsmith import tool


@tool(
    name="search_project_docs",
    description="Search project docs and return matching document IDs.",
)
def search_docs(query: str, limit: int = 5) -> list[str]:
    """Search project documentation by natural language query."""
    return []

Use --all-public to include every public top-level function and Pydantic model:

mcp-toolsmith audit tools.py --execute --all-public
mcp-toolsmith compile tools.py --target mcp --execute --all-public

--all-public is mainly a compatibility path for early alpha behavior. For new Python tool files, prefer @tool.

Use --fail-on to tune CI behavior:

mcp-toolsmith audit tools.py --fail-on error
mcp-toolsmith audit tools.py --fail-on warning
mcp-toolsmith audit tools.py --fail-on never

The default is error.

Provider compatibility profiles

Audit a tool schema for OpenAI-style tool calling:

mcp-toolsmith audit tools.py --profile openai

Audit a tool schema for MCP compatibility:

mcp-toolsmith audit tools.py --profile mcp

Use this in CI:

mcp-toolsmith audit tools.py --profile openai --fail-on warning

The default profile is generic, which keeps the provider-neutral audit behavior from earlier releases.

More copy-pasteable examples live in examples.

Python API

from mcp_toolsmith import audit_file, compile_file

report = audit_file("tools.json")
openai_report = audit_file("tools.json", profile="openai")
report.print()
openai_report.print()

mcp_tools = compile_file("tools.json", target="mcp")
openai_tools = compile_file("tools.json", target="openai")

For trusted Python files:

report = audit_file("tools.py")
report = audit_file("tools.py", execute=True)
mcp_tools = compile_file("tools.py", target="mcp", execute=True)

To opt into broad Python discovery:

report = audit_file("tools.py", execute=True, all_public=True)
mcp_tools = compile_file("tools.py", target="mcp", execute=True, all_public=True)

Checks

Roadmap

License

MIT