Update tools.py

tools.py

@@ -45,8 +45,16 @@ def _download_file_for_task(task_id: str, ext: str) -> str:
 @tool
 def image_tool(task_id: str) -> str:
     """
-    Expects: task_id (str) — a valid image task ID.
-    Returns: image caption from Hugging Face API or error message.
+    TOOL NAME: Image Analysis Tool
+
+    Purpose: When the user asks about images, photos, or visual content, use this tool to get a description of the image.
+
+    Input: A task_id string that identifies the specific image to analyze.
+
+    Example usage:
+    - "What is shown in this image?"
+    - "Describe the contents of the picture"
+    - "What objects are visible in the photo?"
     """
 
     import requests, os
@@ -111,12 +119,16 @@ def image_tool(task_id: str) -> str:
 @tool
 def excel_tool(task_id: str) -> str:
     """
-    Downloads <task_id>.xlsx (if any) and returns a stringified list of
-    records from the specified sheet.  No fallback to user-supplied tables.
-    Expected keys in `task_id`:
-        • task_id            – required (used to download the file)
+    TOOL NAME: Excel Data Analysis Tool
+
+    Purpose: When the user asks about data in spreadsheets, tables, or Excel files, use this tool to read and analyze the data.
 
-    returns: stringified list of records from the specified sheet
+    Input: A task_id string that identifies the specific Excel file to analyze.
+
+    Example usage:
+    - "What data is in this spreadsheet?"
+    - "Analyze the Excel file contents"
+    - "Show me the data from the table"
     """
     print("reached excel_tool")
     sheet   = "Sheet1"
@@ -141,11 +153,16 @@ import openai
 @tool
 def audio_transcriber_tool(task_id: str) -> str:
     """
-    LangGraph tool for transcribing audio via OpenAI's Whisper API.
-    Expects: task_id is a string
-    Returns:
-    "<text or error message>"
-    Always attempts to download the file for the given path or task ID.
+    TOOL NAME: Audio Transcription Tool
+
+    Purpose: When the user asks about audio files, speech, or wants to know what was said in an audio recording, use this tool.
+
+    Input: A task_id string that identifies the specific audio file to transcribe.
+
+    Example usage:
+    - "What is said in this audio file?"
+    - "Transcribe the speech from the recording"
+    - "Convert the audio to text"
     """
     print("reached audio_transcriber_tool")
 
@@ -188,11 +205,16 @@ import requests
 @tool
 def wikipedia_search_tool(wiki_query: str) -> str:
     """
-    Searches Wikipedia for the given query and returns the first 5 pages.
-    Expects: wiki_query is a non‐empty string.
-    Returns: text summary of first matching page or an error message>"
-      
-    If no valid wiki_query is provided, returns {}.
+    TOOL NAME: Wikipedia Search Tool
+
+    Purpose: When the user asks for historical, biographical, scientific, or factual information, use this tool.
+
+    Input: A string describing a topic to search on Wikipedia.
+
+    Example usage:
+    - "Who was Marie Curie?"
+    - "Explain quantum entanglement"
+    - "Tell me about the French Revolution"
     """
     print(f"DEBUG: reached wikipedia_search_tool with query: {wiki_query}")
     try:
@@ -252,9 +274,16 @@ def wikipedia_search_tool(wiki_query: str) -> str:
 @tool
 def arxiv_search_tool(arxiv_query: str) -> str:
     """
-    Searches Arxiv for the given query and returns the first 5 pages.
-    Expects: arxiv_query is a non‐empty string.
-    Returns: text summary of first matching page or an error message>"
+    TOOL NAME: ArXiv Academic Search Tool
+
+    Purpose: When the user asks for academic research, scientific papers, or technical information, use this tool.
+
+    Input: A string describing the academic topic to search for on ArXiv.
+
+    Example usage:
+    - "Find research papers about machine learning"
+    - "What are recent studies on climate change?"
+    - "Search for papers on quantum computing"
     """
     print(f"DEBUG: reached arxiv_search_tool with query: {arxiv_query}")
     try:
@@ -321,12 +350,16 @@ LLM = ChatOpenAI(model_name="gpt-4o-mini", temperature=0.2)
 @tool
 def analyze_code_tool(task_id: str) -> str:
     """
-    Either task_id  OR  (file + task_id)
-    Reads the code (max 400 lines / 10 kB) and asks the LLM for:
-        • plain-language summary
-        • list of key functions/classes
-        • obvious bugs or style smells
-    Returns that analysis as a string.
+    TOOL NAME: Code Analysis Tool
+
+    Purpose: When the user asks about code, programming files, or wants to understand what a script does, use this tool.
+
+    Input: A task_id string that identifies the specific code file to analyze.
+
+    Example usage:
+    - "What does this Python code do?"
+    - "Analyze the code file for bugs"
+    - "Explain the functions in this script"
     """
     print("reached analyze_code_tool")
     code_txt = ""
@@ -357,6 +390,82 @@ def analyze_code_tool(task_id: str) -> str:
     return LLM.invoke(prompt).content.strip()
 
 
+
+# ─────────────────────────── Math Tools ───���───────────────────────────
+
+@tool
+def add_tool(a: float, b: float) -> str:
+    """
+    TOOL NAME: Addition Tool
+
+    Purpose: When the user asks to add numbers or perform addition calculations, use this tool.
+
+    Input: Two numbers (a and b) to add together.
+
+    Example usage:
+    - "What is 25 + 17?"
+    - "Add 3.14 and 2.86"
+    - "Calculate the sum of 100 and 250"
+    """
+    result = a + b
+    return f"Addition result: {a} + {b} = {result}"
+
+@tool
+def subtract_tool(a: float, b: float) -> str:
+    """
+    TOOL NAME: Subtraction Tool
+
+    Purpose: When the user asks to subtract numbers or perform subtraction calculations, use this tool.
+
+    Input: Two numbers (a and b) where b is subtracted from a.
+
+    Example usage:
+    - "What is 50 - 23?"
+    - "Subtract 15.5 from 40.2"
+    - "Calculate 1000 minus 347"
+    """
+    result = a - b
+    return f"Subtraction result: {a} - {b} = {result}"
+
+@tool
+def multiply_tool(a: float, b: float) -> str:
+    """
+    TOOL NAME: Multiplication Tool
+
+    Purpose: When the user asks to multiply numbers or perform multiplication calculations, use this tool.
+
+    Input: Two numbers (a and b) to multiply together.
+
+    Example usage:
+    - "What is 8 × 7?"
+    - "Multiply 12.5 by 4"
+    - "Calculate the product of 15 and 20"
+    """
+    result = a * b
+    return f"Multiplication result: {a} × {b} = {result}"
+
+@tool
+def divide_tool(a: float, b: float) -> str:
+    """
+    TOOL NAME: Division Tool
+
+    Purpose: When the user asks to divide numbers or perform division calculations, use this tool.
+
+    Input: Two numbers (a and b) where a is divided by b.
+
+    Example usage:
+    - "What is 100 ÷ 4?"
+    - "Divide 75 by 3"
+    - "Calculate 144 divided by 12"
+    """
+    if b == 0:
+        return "Division error: Cannot divide by zero"
+    result = a / b
+    return f"Division result: {a} ÷ {b} = {result}"
+
+
+
+
 # def web_search_tool(state: AgentState) -> AgentState:
 #     """
 #     Expects: state["web_search_query"] is a non‐empty string.
@@ -404,56 +513,4 @@ def analyze_code_tool(task_id: str) -> str:
 #     return {
 #         "web_search_query": None,
 #         "web_search_result": result_text
-#     }
-
-# ─────────────────────────── Math Tools ───────────────────────────────
-
-@tool
-def add_tool(a: float, b: float) -> str:
-    """
-    Add two numbers.
-    Args:
-        a: First number
-        b: Second number
-    Returns: The sum of a and b
-    """
-    result = a + b
-    return f"Addition result: {a} + {b} = {result}"
-
-@tool
-def subtract_tool(a: float, b: float) -> str:
-    """
-    Subtract two numbers.
-    Args:
-        a: First number (minuend)
-        b: Second number (subtrahend)
-    Returns: The difference of a minus b
-    """
-    result = a - b
-    return f"Subtraction result: {a} - {b} = {result}"
-
-@tool
-def multiply_tool(a: float, b: float) -> str:
-    """
-    Multiply two numbers.
-    Args:
-        a: First number
-        b: Second number
-    Returns: The product of a and b
-    """
-    result = a * b
-    return f"Multiplication result: {a} × {b} = {result}"
-
-@tool
-def divide_tool(a: float, b: float) -> str:
-    """
-    Divide two numbers.
-    Args:
-        a: First number (dividend)
-        b: Second number (divisor)
-    Returns: The quotient of a divided by b
-    """
-    if b == 0:
-        return "Division error: Cannot divide by zero"
-    result = a / b
-    return f"Division result: {a} ÷ {b} = {result}"
+#     }