Skill: Add a New Agent Tool

Steps

1. Create the tool file at src/medox/agent/tools/tool_<name>.py:

   """One-line description of the data source and lookup strategy."""
   
   from medox.pipeline.config_pipeline import PipelineSettings
   
   def <tool_name>(<param>: str) -> str:
       """
       <What this tool does — written for the LLM, not a human developer.>
   
       Include:
       - What the parameter means and expected format
       - Example values or class names the LLM should pass
       - What the tool returns and how to interpret it
   
       Example: pass 'ANTIVITAMINES K' for warfarine, 'STATINES' for simvastatine.
       """
       settings = PipelineSettings()
       # ... implementation
   

2. Register the tool in src/medox/api/agent.py (TOOLS) and in _dispatch_tool in src/medox/api/app.py.

3. Docstring rules (critical — the LLM uses this to decide when/how to call the tool):

   • Written in English
   • Explain when to use this tool vs other tools
   • Give concrete input examples (especially for ANSM class names)
   • Describe the return format

4. Write the test at tests/agent/test_tool_<name>.py:

   def test_<tool_name>_returns_expected():
       result = <tool_name>.invoke({"<param>": "<known_value>"})
       assert "<expected_substring>" in result
   
   def test_<tool_name>_handles_unknown():
       result = <tool_name>.invoke({"<param>": "nonexistent_xyz"})
       assert result  # returns graceful message, not exception
   

5. Update .claude/rules/agent.md — add the tool to the tools table.

6. Validate:

   uv run pytest tests/agent/test_tool_<name>.py -v
   uv run pytest tests/agent/ -v
   

Rules

• Tool file name: tool_<name>.py — matches the @tool function name
• One @tool per file
• Never raise exceptions — return a descriptive string on error
• Requires Docker stack running for PostgreSQL tools