add-agent-tool

name	add-agent-tool
description	Add a new LangChain tool to the Medox ReAct agent. Use when creating a new tool file, registering it in the graph, and writing its test.
argument-hint	<tool-name>

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 langchain_core.tools import tool
   from medox.pipeline.config_pipeline import PipelineSettings
   
   @tool
   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/agent/graph_agent.py:

   • Add the import
   • Add to the tools = [...] list passed to build_agent()

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 ChromaDB/PostgreSQL tools