TheRock/rocm-systems/experimental/python/perfxpert/docs/contributing/tools.md

Contributing: new tool

What you're adding

A deterministic Python function that an agent can call. Tools are the pure-function layer between agents and data — no LLM calls, no I/O except knowledge/*.yaml loads and SQL reads.

File locations

• Implementation: perfxpert/tools/<module>.py
• Tests: tests/test_tools/test_<module>.py

Template

"""<module> — <one-line purpose>.

Tool class: READ_ONLY (MCP-safe) or EXECUTION (in-process only).

Tool classes are enumerated in the multi-agent design spec (local
contributor doc, not tracked in the repo) — Appendix A.
"""

from typing import Any, Dict

from perfxpert.knowledge import load_yaml
from perfxpert.tools._class import ToolClass, tool_class


@tool_class(ToolClass.READ_ONLY)
def my_tool(arg: str) -> Dict[str, Any]:
    """<docstring>

    Args:
        arg: <what>

    Returns:
        <shape>

    Raises:
        KeyError: if <condition>
    """
    data = load_yaml("my_yaml")
    # ...
    return {...}

Schema constraints (CI-enforced)

• Type hints mandatory on args + return
• Docstring in Google style
• No external I/O (filesystem writes, network) without ToolClass.EXECUTION
• < 100 ms per call (p99) — covered by a timing test

Tests you must add

• test_<name>_returns_expected_shape — happy path
• test_<name>_raises_on_unknown_input — error path
• test_<name>_is_read_only_class — MCP policy
• test_<name>_under_50ms — performance

Review requirements

• 1 core reviewer
• CI green (unit + MCP-exposure + type check)

Common pitfalls

• Don't re-implement what a knowledge/*.yaml already covers — look up instead
• @tool_class decorator MUST come after docstring (otherwise Pydantic schema generation skips it)
• Avoid f-string SQL for integer bound-params — use f-strings for INTEGER WHERE/LIMIT
• Pure Python stdlib + yaml + Pydantic only — no heavy deps

Related docs

• Design spec: Appendix A (tool inventory)
• Existing tools under perfxpert/tools/ as references