system prompt and github tool desc. update

agent/prompts/system_prompt.yaml

@@ -5,52 +5,53 @@ system_prompt: |
 
   # Task Approach
 
-  **CRITICAL: Research First, Then Implement**
+  **CRITICAL: You always research first, then implement. You only make implementations that are guided by examples, best practices, or documentation.**
 
   For ANY implementation task (training, fine-tuning, inference, data processing, etc.):
   1. **FIRST**: Search HF documentation to find the recommended approach
      - This is MANDATORY before writing any code or making implementation decisions
      - Use `explore_hf_docs` to discover documentation structure for relevant libraries (e.g., "trl", "transformers", "diffusers")
+     - Use `github_find_examples` and `github_read_file` to discover best-practices on these libraries to reuse.
      - Use `fetch_hf_docs` to retrieve full content from specific documentation pages
-     - Use `search_hf_api_endpoints` to find API endpoints with usage examples
+     - Use `search_hf_api_endpoints` to find API endpoints (e.g. spaces, models, datasets, discussions, users, orgs, papers etc.) with usage examples and curl examples.
      - Research what libraries to use, find code examples, understand best practices
-     - Skip ONLY for simple factual questions (e.g., "What is LoRA?")
+     - Skip ONLY for simple factual questions (e.g., "What is LoRA?"). 
 
-  2. **THEN**: Formulate a plan based on research findings. Pass todos to the PlanTool. Update as progress is made.
+  2. **THEN**: Formulate a plan based on research findings. Pass todos to the `plan_tool`. Update as progress is made.
 
   3. **FINALLY**: Implement using researched approaches
      - Search for relevant models/datasets on HF Hub
+     - Always validate data structure and format before using it (libraries need specific formats, see documentation).
      - Use all available tools to complete the task
-     - Leverage existing resources before creating new ones
-     - Invoke multiple independent tools simultaneously for efficiency
+     - Always leverage existing implementations and resources before creating new ones
+     - Use multiple independent tools concurrently for efficiency
 
   # Autonomy / Subordinate trade-off.
 
   Your main goal is to achieve what the user asked. For this:
-  1. Take action, follow-up, launch jobs. Ask for as little action from the user as possible. Do not ask them to do things you could do via a script.
+  1. Research, then take action, follow-up, launch jobs. Ask for as little action from the user as possible. Do not ask them to do things you could do via a script or tool.
 
   However !! :
   1. Don't surprise the user with costly, irreversible, or strange actions without asking.
-  2. Don't be shy to ask questions if needed.
+  2. Don't be shy to ask clarifying questions if needed.
   3. Don't be overly talkative, explaining everything after a task ended.
 
   
   # Conventions
 
   - **ALWAYS search documentation BEFORE implementing** any ML workflow (training, inference, data processing, etc.) - This is non-negotiable
-  - Use `explore_hf_docs`, `fetch_hf_docs`, and `search_hf_api_endpoints` to research the correct approach
-  - Never assume you know the correct library, method, or approach - you must verify with documentation first
+  - Use `explore_hf_docs`, `github_find_examples`, `fetch_hf_docs`, and `search_hf_api_endpoints` to research the correct approach
+  - Never assume you know the correct library, method, or approach - you must verify with documentation first. Documentation is the ultimate source of truth.
   - Base your implementation on researched best practices, not general knowledge or assumptions
   - Always search Hugging Face Hub for existing resources before suggesting custom implementations
   - Keep in mind that a space is a repo, so you can create a space directly by uploading files that way. Repos should also be used to store files permanently : post-execution, files from jobs are not available.
   - To run jobs, you must always pass the whole content of the file to execute. No files are available on server. Your local files and distant files are entirely seperate scopes.
   - The HF_TOKEN is automatically loaded from the environment variables.
-  - 
   - When referencing models, datasets, or papers, include direct links from search results
-  - Before processing any dataset: inspect its actual structure first using the mcp__hf-mcp-server__hub_repo_details tool. Never assume column names: verify them beforehand.
-  - Follow ML best practices: proper train/val/test splits, reproducibility, evaluation metrics
+  - Before processing any dataset: inspect its actual structure first using the `hub_repo_details` tool. Never assume column names, datarow structure, or format: verify them beforehand.
+  - Follow ML best practices: proper train/val/test splits, reproducibility, evaluation metrics, pushing to hub.
   - Unless absolutely necessary, don't ask user for action. This does not apply to follow-up questions you have.
-  - For training tasks, consider compute requirements and choose appropriate hardware.
+  - For training tasks, consider compute requirements and choose appropriate hardware based on this formula: approx_VRAM_needed = N_params × bytes_per_param × 1.5.
   - Never expose or log API keys, tokens, or secrets. Do not assume keys or secrets are available. Only Hugging Face private resources are available.
 
   # Communication Style

agent/tools/github_find_examples.py

@@ -12,25 +12,19 @@ from thefuzz import fuzz
 
 from agent.tools.types import ToolResult
 
-# Global list of example-related keywords for fuzzy matching
+# In order of priority (lower index = higher priority for sorting)
 EXAMPLE_PATTERNS = [
-    # Core example patterns
+    "scripts",
+    # General example patterns (catch-all, lower priority)
     "examples",
     "example",
-    "samples",
-    "sample",
-    "demos",
-    "demo",
+    # Notebook patterns
+    "notebooks",
+    "notebook",
     # Tutorial/learning patterns
     "tutorials",
     "tutorial",
-    "guides",
-    "guide",
     "quickstart",
-    "getting-started",
-    "getting_started",
-    "howto",
-    "how-to",
     "walkthroughs",
     "walkthrough",
     # Cookbook/recipe patterns
@@ -38,28 +32,24 @@ EXAMPLE_PATTERNS = [
     "cookbooks",
     "recipes",
     "recipe",
-    # Notebook patterns (common in ML/data science)
-    "notebooks",
-    "notebook",
-    "ipynb",
-    # Starter/template patterns
-    "starter",
-    "starters",
-    "templates",
-    "template",
-    "boilerplate",
-    # Snippet/use-case patterns
-    "snippets",
-    "snippet",
+    # Demo/sample patterns
+    "demos",
+    "demo",
+    "samples",
+    "sample",
+    # Other patterns
+    "guides",
+    "guide",
+    "getting-started",
+    "getting_started",
+    "playground",
+    "howto",
+    "how-to",
     "use-cases",
     "usecases",
     "use_cases",
-    # Showcase/playground patterns
-    "showcase",
-    "playground",
     "sandbox",
-    # Script patterns
-    "scripts",
+    "showcase",
 ]
 
 
@@ -178,6 +168,45 @@ def _score_against_keyword(file_path: str, keyword: str) -> int:
     return max(partial_score, token_score)
 
 
+def _get_pattern_priority(file_path: str) -> tuple[int, int, int]:
+    """
+    Get priority of a file path based on which example pattern directory it's in.
+
+    Returns: (in_examples_dir, pattern_priority, path_depth)
+    - in_examples_dir: 0 if in examples/ directory, 1 otherwise (lower is better)
+    - pattern_priority: Index in EXAMPLE_PATTERNS (lower is better), or 999 if no match
+    - path_depth: Number of path segments (lower is better)
+
+    Note: Prioritizes files in "examples/" directory first, then by most specific pattern match.
+    E.g., "examples/scripts/train.py" is better than "scripts/util.py"
+    """
+    path_lower = file_path.lower()
+    path_parts = path_lower.split("/")
+
+    # Check if file is in examples/ directory (highest priority)
+    in_examples_dir = 0 if (path_parts[0] in ["examples", "example"]) else 1
+
+    # Find ALL matching patterns and use the best (lowest index) one
+    # But prefer deeper matches (more specific) over shallow ones
+    best_priority = 999
+    best_depth_at_match = -1
+
+    for i, pattern in enumerate(EXAMPLE_PATTERNS):
+        # Check if pattern appears as a directory component in the path
+        if pattern in path_parts:
+            # Find the depth where this pattern appears (rightmost occurrence)
+            depth = len(path_parts) - 1 - path_parts[::-1].index(pattern)
+
+            # Prefer deeper matches, or better priority if at same depth
+            if depth > best_depth_at_match or (
+                depth == best_depth_at_match and i < best_priority
+            ):
+                best_priority = i
+                best_depth_at_match = depth
+
+    return (in_examples_dir, best_priority, len(path_parts))
+
+
 def _handle_repo_tree_errors(
     all_files: List[Dict[str, Any]],
     error: str,
@@ -308,23 +337,42 @@ def find_examples(
                 "totalResults": 0,
                 "resultsShared": 0,
             }
+
+        # Sort by keyword score (descending) for best matches first
+        scored_files.sort(key=lambda x: x["score"], reverse=True)
     else:
-        # No keyword: use example pattern scores
-        scored_files = [
-            {**file, "score": file["example_score"]}
-            for file in example_files
-            if file["example_score"] >= min_score
-        ]
+        # No keyword: prioritize by pattern directory, then path depth
+        scored_files = []
+        for file in example_files:
+            in_examples_dir, pattern_priority, path_depth = _get_pattern_priority(
+                file["path"]
+            )
+            scored_files.append(
+                {
+                    **file,
+                    "score": file["example_score"],
+                    "in_examples_dir": in_examples_dir,
+                    "pattern_priority": pattern_priority,
+                    "path_depth": path_depth,
+                }
+            )
 
         if not scored_files:
             return {
-                "formatted": f"No example files found in {org}/{repo} with score >= {min_score}.",
+                "formatted": f"No example files found in {org}/{repo}.",
                 "totalResults": 0,
                 "resultsShared": 0,
             }
 
-    # Sort by score (descending) for best matches first
-    scored_files.sort(key=lambda x: x["score"], reverse=True)
+        # Sort by: 1) files in examples/ dir first, 2) pattern priority (scripts > datasets > etc), 3) path depth, 4) path name
+        scored_files.sort(
+            key=lambda x: (
+                x["in_examples_dir"],
+                x["pattern_priority"],
+                x["path_depth"],
+                x["path"],
+            )
+        )
 
     # Limit results
     results = scored_files[:max_results]
@@ -357,35 +405,54 @@ def find_examples(
 GITHUB_FIND_EXAMPLES_TOOL_SPEC = {
     "name": "github_find_examples",
     "description": (
-        "Find example files in a GitHub repository using fuzzy matching.\n\n"
-        "This tool uses fuzzy string matching to find files related to a keyword or common example patterns. "
-        "It calculates similarity scores and returns the best matches.\n\n"
-        "Global example keywords (always fuzzy matched): example, tutorial, demo, quickstart, guide, sample\n\n"
-        "If the repository is not found, it returns similar repositories sorted by star count.\n\n"
-        "Features:\n"
-        "- Fuzzy matching using Levenshtein distance\n"
-        "- Sorted by match score (best matches first)\n"
-        "- Auto-suggests similar repos if target not found\n"
-        "- Configurable minimum score threshold\n\n"
-        "## Examples:\n\n"
-        "**Find GRPO examples in TRL:**\n"
-        "{'keyword': 'grpo', 'repo': 'trl', 'org': 'huggingface'}\n"
-        "→ Matches: examples/scripts/grpo_agent.py, examples/scripts/gspo.py\n\n"
-        "**Find tutorial files in transformers:**\n"
-        "{'keyword': 'tutorial', 'repo': 'transformers', 'org': 'huggingface'}\n\n"
-        "**Find any example files (no keyword):**\n"
-        "{'repo': 'pytorch', 'org': 'pytorch'}\n"
-        "→ Uses global example keywords for matching\n\n"
-        "**Adjust minimum score:**\n"
-        "{'keyword': 'bert', 'repo': 'transformers', 'org': 'huggingface', 'min_score': 70}\n\n"
-        "Returns list of matching files with fuzzy match scores, paths, sizes, and URLs."
+        "Discover best practices, reusable scripts, tutorials, and demos for usinga specific library or framework. This is an important step before implementing anything ML related.",
+        "Use together with github_read_file tool.\n\n"
+        "## When to use this tool\n\n"
+        "- ALWAYS before implementing any training/inference/benchmarking or other ML related code or answering how-to question.\n"
+        "- When exploring a new repository and need to understand how to use it\n"
+        "## How it works\n\n"
+        "1. Fetches all (examples, tutorials, demos, notebooks, scripts, etc.) from the repository\n"
+        "2. If keyword provided, scores found files against the keyword using fuzzy matching\n"
+        "3. Returns best matches sorted by relevance score\n"
+        "## Examples\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Find GRPO/SFT/DPO/RLOO etc training examples\n"
+        "// Task: Starting GRPO fine-tuning project, need reference implementations\n"
+        "{\n"
+        "  keyword: 'grpo',\n"
+        "  repo: 'trl',\n"
+        "  org: 'huggingface'\n"
+        "}\n"
+        "// Returns: examples/scripts/grpo_agent.py, examples/scripts/grpo_vlm.py\n"
+        "// Next step: Use github_read_file to study the implementation\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Discover all training examples in TRL\n"
+        "// Task: Exploring available training methods before choosing approach\n"
+        "{\n"
+        "  repo: 'trl',\n"
+        "  org: 'huggingface',\n"
+        "  max_results: 20\n"
+        "}\n"
+        "// Lists all example scripts: PPO, DPO, GRPO, reward modeling, etc.\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Find LoRA fine-tuning examples\n"
+        "// Task: Learning parameter-efficient fine-tuning with PEFT\n"
+        "{\n"
+        "  keyword: 'lora',\n"
+        "  repo: 'peft',\n"
+        "  org: 'huggingface'\n"
+        "}\n"
+        "// Discovers LoRA configuration and training examples\n"
+        "</example>",
     ),
     "parameters": {
         "type": "object",
         "properties": {
             "keyword": {
                 "type": "string",
-                "description": "Keyword to fuzzy match against file paths (e.g., 'grpo', 'bert'). Optional.",
+                "description": "Keyword to fuzzy match against file paths (e.g., 'grpo', 'sft').",
             },
             "repo": {
                 "type": "string",

agent/tools/github_list_repos.py

@@ -200,26 +200,39 @@ def list_repos(
 
 # Tool specification
 GITHUB_LIST_REPOS_TOOL_SPEC = {
-    "name": "list_repos",
+    "name": "github_list_repos",
     "description": (
-        "List and sort repositories for any GitHub user or organization.\n\n"
-        "Uses GitHub Search API for efficient sorting by stars, forks, update date, or creation date.\n"
-        "Returns comprehensive repository information including:\n"
-        "- Stars, forks, and open issues count\n"
-        "- Primary programming language\n"
-        "- Repository topics/tags\n"
-        "- Last update timestamp\n"
-        "- Direct URLs\n\n"
-        "## Examples:\n\n"
-        "**List top 10 starred Hugging Face repos:**\n"
-        "{'owner': 'huggingface', 'owner_type': 'org', 'sort': 'stars', 'limit': 10}\n\n"
-        "**List recently updated Microsoft repos:**\n"
-        "{'owner': 'microsoft', 'sort': 'updated', 'order': 'desc', 'limit': 5}\n\n"
-        "**List all repos for a user:**\n"
-        "{'owner': 'torvalds', 'owner_type': 'user', 'sort': 'stars'}\n\n"
-        "**Find most forked Google repos:**\n"
-        "{'owner': 'google', 'sort': 'forks', 'order': 'desc', 'limit': 20}\n\n"
-        "Perfect for discovering popular projects, finding active repositories, or exploring an organization's work."
+        "List and discover repositories for any GitHub user or organization with flexible sorting.\n\n"
+        "Returns comprehensive repository information including stars, forks, language, topics, and direct URLs. "
+        "Sorts by stars, forks, update date, or creation date.\n\n"
+        "## When to use this tool\n\n"
+        "- When you need to find libraries to use in your implementation, or to explore what repositories exist for a task.\n"
+        "- When debugging an error to looking up if others are having the same issues in repositories."
+        "- When finding the most popular or active projects for a user or org\n"
+        "## Examples\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Discover HF libraries for RLHF/alignment\n"
+        "// Use case: Find the right library for training with human feedback\n"
+        "{\n"
+        "  owner: 'huggingface',\n"
+        "  owner_type: 'org',\n"
+        "  sort: 'stars',\n"
+        "  limit: 10\n"
+        "}\n"
+        "// Returns: transformers, trl, peft, accelerate, diffusers...\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Check for recently updated HF repos\n"
+        "// Use case: Find actively maintained libraries with latest features\n"
+        "{\n"
+        "  owner: 'huggingface',\n"
+        "  owner_type: 'org',\n"
+        "  sort: 'updated',\n"
+        "  order: 'desc',\n"
+        "  limit: 15\n"
+        "}\n"
+        "// Helps identify which repos have recent improvements/fixes\n"
+        "</example>"
     ),
     "parameters": {
         "type": "object",

agent/tools/github_read_file.py

@@ -248,24 +248,49 @@ def read_file(
 
 # Tool specification
 GITHUB_READ_FILE_TOOL_SPEC = {
-    "name": "read_file",
+    "name": "github_read_file",
     "description": (
-        "Read file contents from any GitHub repository with precise line range control.\n\n"
-        "Features:\n"
-        "- Read entire files or specific line ranges\n"
-        "- Auto-truncates large files to 300 lines (with warning)\n"
-        "- Works with any branch, tag, or commit SHA\n"
-        "- Returns file metadata (SHA, size, line count)\n"
-        "## Examples:\n\n"
-        "**Read entire README:**\n"
-        "{'repo': 'huggingface/transformers', 'path': 'README.md'}\n\n"
-        "**Read specific line range:**\n"
-        "{'repo': 'huggingface/trl', 'path': '/examples/scripts/grpo_vlm.py', 'line_start': 100, 'line_end': 150}\n\n"
-        "**Read from specific branch:**\n"
-        "{'repo': 'python/cpython', 'path': 'Lib/ast.py', 'ref': 'main', 'line_start': 1, 'line_end': 50}\n\n"
-        "**Read from specific commit:**\n"
-        "{'repo': 'github/github-mcp-server', 'path': 'pkg/github/search.go', 'ref': 'abc123def'}\n\n"
-        "Perfect for examining code, reading documentation, or investigating specific implementations."
+        "Read file contents from any GitHub repository with line range support.\n\n"
+        "Fetches exact file contents in the given line range (default 300 lines, use line_start/line_end adjust). \n\n"
+        "## When to use this tool\n\n"
+        "- When reading example code, implementations, or documentation on a specific github file\n"
+        "- When you found a file via github_list_repos, or github_find_examples and need its contents\n"
+        "- When investigating specific code sections with line ranges\n"
+        "- When reading from specific branches, tags, or commits\n"
+        "## When NOT to use this tool\n\n"
+        "- When you don't know the exact file path beforehand (use github_search_code or github_find_examples first)\n\n"
+        "## Examples\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Reading example code from for GRPO training with TRL\n"
+        "// Use case: Read trainer class to understand API and methods\n"
+        "{\n"
+        "  repo: 'huggingface/trl',\n"
+        "  path: 'trl/trainer/grpo_trainer.py',\n"
+        "  line_start: 1,\n"
+        "  line_end: 200\n"
+        "}\n"
+        "// Read class definition and constructor to understand parameters\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Study complete training script\n"
+        "// Use case: Learn end-to-end VLM fine-tuning with GRPO\n"
+        "{\n"
+        "  repo: 'huggingface/trl',\n"
+        "  path: 'examples/scripts/grpo_vlm.py'\n"
+        "}\n"
+        "// Returns first 300 lines of the file\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Check configuration patterns\n"
+        "// Use case: Learn how to structure training configs\n"
+        "{\n"
+        "  repo: 'huggingface/transformers',\n"
+        "  path: 'examples/pytorch/language-modeling/run_clm.py',\n"
+        "  line_start: 50,\n"
+        "  line_end: 150\n"
+        "}\n"
+        "// Read argument parsing and config setup section\n"
+        "</example>"
     ),
     "parameters": {
         "type": "object",

agent/tools/github_search_code.py

@@ -332,46 +332,82 @@ def search_code(
 
 # Tool specification
 GITHUB_SEARCH_CODE_TOOL_SPEC = {
-    "name": "search_code",
+    "name": "github_search_code",
     "description": (
-        "Search for code patterns across GitHub with intelligent pattern matching.\n\n"
-        "This tool automatically maps your patterns to GitHub's Code Search API:\n\n"
-        "## Repository Patterns:\n"
-        "- **Exact repo**: `'huggingface/trl'` → Searches only that repo\n"
-        "- **Organization**: `'huggingface'` or `'huggingface/*'` → All repos in org\n"
-        "- **All repos**: `'*/*'` or omit → Searches all GitHub\n"
-        "- Wildcards like `'huggingface/trl*'` automatically use client-side filtering\n\n"
-        "## Path Patterns:\n"
+        "Search for code patterns across GitHub repositories with intelligent pattern matching.\n\n"
+        "Searches for specific code patterns, functions, classes, or implementations across GitHub. "
+        "Intelligently maps patterns to GitHub's Code Search API for efficient server-side filtering, "
+        "with automatic client-side filtering for complex patterns. Returns code snippets with context.\n\n"
+        "## When to use this tool\n\n"
+        "- When searching for specific code patterns, functions, or classes across repositories\n"
+        "- When looking for implementation examples of specific methods or APIs\n"
+        "- When you need to find where specific code exists across multiple files or repos\n"
+        "- When investigating how a feature is implemented in different repositories\n"
+        "- When searching for TODO comments, specific patterns, or code structures\n"
+        "- Use this for searching actual implementation code (not examples - use github_find_examples for those)\n\n"
+        "## When NOT to use this tool\n\n"
+        "- When looking for example files or tutorials (use github_find_examples instead)\n"
+        "- When you already know the exact file path (use github_read_file directly)\n"
+        "- When you need to list repositories (use github_list_repos instead)\n\n"
+        "## Repository Patterns\n\n"
+        "- **Exact repo**: `'huggingface/trl'` → Searches only that repository\n"
+        "- **Organization**: `'huggingface'` or `'huggingface/*'` → All repos in organization\n"
+        "- **All GitHub**: `'*/*'` or omit repo_pattern → Searches across all GitHub\n"
+        "- **Wildcards**: `'huggingface/trl*'` → Automatic client-side filtering for complex patterns\n\n"
+        "## Path Patterns\n\n"
         "- **Extension**: `'*.py'` or `'**/*.py'` → All Python files\n"
-        "- **Directory**: `'src/**/*.js'` → JavaScript files in src/ (client-filtered)\n"
+        "- **Directory**: `'src/**/*.js'` → JavaScript files in src/ directory (client-filtered)\n"
         "- **Pattern**: `'test_*.py'` → Files matching pattern (client-filtered)\n"
         "- **Exact path**: `'README.md'` → Specific file\n\n"
-        "## How It Works:\n"
-        "1. Converts patterns to GitHub API filters (server-side, fast)\n"
-        "2. Falls back to client-side filtering for complex patterns\n"
-        "3. Returns code snippets with line numbers and URLs\n\n"
-        "## Examples:\n\n"
-        "**Search for function in specific repo:**\n"
-        "```python\n"
-        "{'query': 'def train', 'repo_pattern': 'huggingface/trl', 'path_pattern': '*.py'}\n"
-        "```\n\n"
-        "**Search across entire organization:**\n"
-        "```python\n"
-        "{'query': 'GRPOTrainer', 'repo_pattern': 'huggingface', 'path_pattern': '*.py'}\n"
-        "```\n\n"
-        "**Search specific directory pattern:**\n"
-        "```python\n"
-        "{'query': 'TODO', 'repo_pattern': 'facebook/react', 'path_pattern': 'src/**/*.js'}\n"
-        "```\n\n"
-        "**Regex search across GitHub:**\n"
-        "```python\n"
-        "{'query': r'class \\w+Trainer', 'path_pattern': '*.py', 'regex': True}\n"
-        "```\n\n"
-        "**Search all repos (no filter):**\n"
-        "```python\n"
-        "{'query': 'import transformers', 'path_pattern': '*.py', 'max_results': 50}\n"
-        "```\n\n"
-        "Perfect for finding code patterns, learning from examples, or exploring implementations."
+        "## How it works\n\n"
+        "1. Parses repository and path patterns\n"
+        "2. Converts to GitHub API filters when possible (server-side, fast)\n"
+        "3. Falls back to client-side filtering for complex patterns\n"
+        "4. Returns code snippets with line numbers, URLs, and file refs\n"
+        "5. Results can be used directly with github_read_file tool\n\n"
+        "## Examples\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Find how AutoModelForCausalLM is used\n"
+        "// Use case: Learning best practices for loading LLMs in TRL\n"
+        "{\n"
+        "  query: 'AutoModelForCausalLM.from_pretrained',\n"
+        "  repo_pattern: 'huggingface/trl',\n"
+        "  path_pattern: '*.py'\n"
+        "}\n"
+        "// Finds all model loading patterns with quantization, device_map, etc.\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Discover TrainingArguments configurations\n"
+        "// Use case: Setting up training hyperparameters correctly\n"
+        "{\n"
+        "  query: 'TrainingArguments',\n"
+        "  repo_pattern: 'huggingface/transformers',\n"
+        "  path_pattern: 'examples/**/*.py',\n"
+        "  max_results: 10\n"
+        "}\n"
+        "// Shows various TrainingArguments setups across different tasks\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Find dataset preprocessing patterns\n"
+        "// Use case: Learning how to prepare data for instruction tuning\n"
+        "{\n"
+        "  query: 'map(tokenize',\n"
+        "  repo_pattern: 'huggingface',\n"
+        "  path_pattern: '*.py'\n"
+        "}\n"
+        "// Discovers tokenization and dataset mapping patterns\n"
+        "</example>\n\n"
+        "<example>\n"
+        "// ML Workflow Step: Find all Trainer class implementations\n"
+        "// Use case: Understanding available trainer variants for different tasks\n"
+        "{\n"
+        "  query: 'class \\\\w+Trainer\\\\(',\n"
+        "  repo_pattern: 'huggingface/trl',\n"
+        "  path_pattern: 'trl/trainer/**/*.py',\n"
+        "  regex: true\n"
+        "}\n"
+        "// Lists: GRPOTrainer, DPOTrainer, PPOTrainer, RewardTrainer, etc.\n"
+        "</example>"
     ),
     "parameters": {
         "type": "object",