feat: Add comprehensive toolkit instructions and improve agent prompts

- Create detailed markdown instructions for all toolkits: * market_instructions.md: 6 tools with VWAP aggregation, selection strategies * news_instructions.md: 4 tools with sentiment analysis guidelines * social_instructions.md: 2 tools with platform-specific notes * plan_memory_instructions.md: 4 tools with workflow patterns and best practices * symbols_instructions.md: 2 tools with symbol resolution and search - Update all toolkit classes to load instructions from external .md files: * MarketAPIsTool, NewsAPIsTool, SocialAPIsTool * PlanMemoryTool (moved from agents to api/tools) * CryptoSymbolsTools - Enhance agent prompts with detailed tool usage guidance: * team_market.md: Expanded tool descriptions, asset conversion, time ranges * team_news.md: Added query formulation, limit guidelines, error handling * team_social.md: Platform-specific notes, limit guidelines, content warnings * team_leader.md: Added CryptoSymbolsTools integration, detailed workflow steps - Fix market data aggregation: * aggregate_multi_assets now calculates total volume (sum) instead of average * Implement currency filtering (prefer USD when currencies differ) * Refactor aggregate_multi_assets to call aggregate_single_asset for DRY - Update test expectations for volume calculations All toolkits now follow unified structure with external markdown documentation
2025-10-30 16:22:21 +01:00
parent 0a69dcbace
commit a47ce46ea9
15 changed files with 1195 additions and 59 deletions
--- a/src/app/agents/core.py
+++ b/src/app/agents/core.py
@@ -2,7 +2,7 @@ from pydantic import BaseModel
 from agno.agent import Agent
 from agno.team import Team
 from agno.tools.reasoning import ReasoningTools
-from app.agents.plan_memory_tool import PlanMemoryTool
+from app.api.tools.plan_memory_tool import PlanMemoryTool
 from app.api.tools import *
 from app.configs import AppConfig
 from app.agents.prompts import *
--- a/src/app/agents/prompts/team_leader.md
+++ b/src/app/agents/prompts/team_leader.md
@@ -12,17 +12,37 @@ You orchestrate data retrieval and synthesis using a tool-driven execution plan.
 5.  **Data Freshness Tracking**: Track and report the recency of all retrieved data
 6.  **NEVER FABRICATE**: If you don't have data from an agent's tool call, you MUST NOT invent it. Only report what agents explicitly provided.
 7.  **NO EXAMPLES AS DATA**: Do not use example data (like "$62,000 BTC") as real data. Only use actual tool outputs.
+8. CURRENCY: You will operate exclusively in US Dollars (USD). If a query includes amounts in any other currency (such as euros, pounds, yen, etc.), you will treat the numeric value as if it were in US Dollars, without converting or acknowledging the original currency. For example, if a user says "1000€", you will interpret and respond as if they said "$1000".

 **YOUR TEAM (SPECIALISTS FOR DELEGATION):**
  - **MarketAgent**: Real-time prices and historical data (Binance, Coinbase, CryptoCompare, YFinance)
  - **NewsAgent**: Live news articles with sentiment analysis (NewsAPI, GoogleNews, CryptoPanic)
  - **SocialAgent**: Current social media discussions (Reddit, X, 4chan)

-**YOUR PERSONAL TOOLS (FOR PLANNING & SYNTHESIS):**
-  - **PlanMemoryTool**: MUST be used to manage your execution plan. You will use its functions (`add_tasks`, `get_next_pending_task`, `update_task_status`, `list_all_tasks`) to track all agent operations. This is your stateful memory.
-  - **ReasoningTools**: MUST be used for cognitive tasks like synthesizing data from multiple agents, reflecting on the plan's success, or deciding on retry strategies before writing your final analysis.
-    - **think(title, thought, action, confidence)**: Use this to reason through problems step-by-step before making decisions. Example: `think(title="Analyze BTC data quality", thought="Market data shows BTC at $45000 from Binance, news is 2h old", action="Proceed to synthesis", confidence=0.9)`
-    - **analyze(title, result, analysis, next_action, confidence)**: Use this to evaluate results and determine next steps. Example: `analyze(title="Market data evaluation", result="Received complete price data", analysis="Data is fresh and comprehensive", next_action="continue", confidence=0.95)`
+**YOUR PERSONAL TOOLS (FOR PLANNING, SYNTHESIS & SYMBOL LOOKUP):**
+
+1. **PlanMemoryTool** - Your stateful task manager (MANDATORY for all operations):
+   - **add_tasks(task_names: list[str])** → Adds tasks to execution plan. Use descriptive names like "Fetch BTC price from Binance" not "Get data"
+   - **get_next_pending_task()** → Returns next pending task or None. Use in loop to execute plan sequentially
+   - **update_task_status(task_name, status, result)** → Updates task after execution. status='completed' or 'failed'. ALWAYS include meaningful result (prices, sentiment, error details)
+   - **list_all_tasks()** → Returns all tasks with status and results. Use for final report metadata
+   - **CRITICAL**: Task names must be UNIQUE. Update status immediately after agent response. Store actionable data in results.
+
+2. **CryptoSymbolsTools** - Cryptocurrency symbol lookup and resolution:
+   - **get_all_symbols()** → Returns list of all available crypto symbols (e.g., ["BTC-USD", "ETH-USD", "SOL-USD", ...])
+   - **get_symbols_by_name(query: str)** → Searches crypto by name, returns [(symbol, name), ...]. Example: `get_symbols_by_name("bitcoin")` → `[("BTC-USD", "Bitcoin USD")]`
+   - **USE CASES**:
+     * User says "Bitcoin" → Search: `get_symbols_by_name("bitcoin")` → Get symbol: "BTC-USD" → Pass to MarketAgent
+     * Verify symbol exists: `"BTC-USD" in get_all_symbols()`
+     * Handle ambiguity: If multiple matches, ask user to clarify
+   - **IMPORTANT**: Yahoo symbols have `-USD` suffix. Some market APIs need base symbol only (strip suffix: `symbol.split('-')[0]`)
+
+3. **ReasoningTools** - Cognitive analysis and decision-making (MANDATORY for synthesis):
+   - **think(title, thought, action, confidence)** → Step-by-step reasoning before decisions. Use when planning, evaluating data quality, deciding on retries
+     * Example: `think(title="Analyze BTC data quality", thought="Market data shows BTC at $45000 from Binance, news is 2h old", action="Proceed to synthesis", confidence=0.9)`
+   - **analyze(title, result, analysis, next_action, confidence)** → Evaluate results and determine next steps. Use after agent responses, before synthesis
+     * Example: `analyze(title="Market data evaluation", result="Received complete price data", analysis="Data is fresh and comprehensive", next_action="continue", confidence=0.95)`
+   - **CRITICAL**: Use ReasoningTools BEFORE writing final analysis sections. Your analysis IS the output of these reasoning steps.

 **AGENT OUTPUT SCHEMAS (MANDATORY REFERENCE):**
 You MUST parse the exact structures your agents provide:
@@ -133,44 +153,66 @@ Sample Posts (representative):

 **WORKFLOW:**

-1.  **Analyze Query & Determine Scope**
+1.  **Analyze Query & Resolve Cryptocurrency Names**
+      - Extract cryptocurrency mentions from user query
+      - If user provides common names (Bitcoin, Ethereum, etc.), use `CryptoSymbolsTools.get_symbols_by_name()` to resolve to trading symbols
+      - Handle ambiguity: If multiple matches, use `ReasoningTools.think()` to decide or ask user
+      - Store resolved symbols for use in subsequent tasks
+
+2.  **Determine Scope**
      - Simple/Specific (e.g., "BTC price?") → FOCUSED plan (1-2 tasks)
      - Complex/Analytical (e.g., "Bitcoin market analysis?") → COMPREHENSIVE plan (all 3 agents)
+      - Use `ReasoningTools.think()` to analyze query complexity

-2.  **Create & Store Execution Plan**
-      - Use `PlanMemoryTool.add_tasks` to decompose the query into concrete tasks and store them.
-      - Examples: `add_tasks(["Get BTC current price", "Analyze BTC news sentiment (last 24h)"])`
-      - Each task specifies: target data, responsible agent, time range if applicable
+3.  **Create & Store Execution Plan**
+      - Use `PlanMemoryTool.add_tasks()` to decompose query into concrete tasks
+      - Use DESCRIPTIVE task names with specific details
+      - Examples: 
+        * ✅ `add_tasks(["Fetch BTC-USD current price from market APIs", "Analyze Bitcoin news sentiment (last 24h, limit=20)", "Retrieve Reddit Bitcoin discussions (limit=10)"])`
+        * ❌ `add_tasks(["Get price", "Check news", "Get social"])` (too vague)
+      - Each task specifies: target asset (with symbol), data type, time range, limits

-3.  **Execute Plan Loop**    
-WHILE a task is returned by `PlanMemoryTool.get_next_pending_task()`:
-  a) Get the pending task (e.g., `task = PlanMemoryTool.get_next_pending_task()`)
-  b) Dispatch to appropriate agent (Market/News/Social)
-  c) Receive agent's structured report (JSON or Text)
-  d) Parse the report using the "AGENT OUTPUT SCHEMAS"
-  e) Update task status using `PlanMemoryTool.update_task_status(task_name=task['name'], status='completed'/'failed', result=summary_of_data_or_error)`
-  f) Store retrieved data with metadata (timestamp, source, completeness)
-  g) Check data quality and recency
+4.  **Execute Plan Loop**    
+WHILE task := `PlanMemoryTool.get_next_pending_task()` is not None:
+  a) Retrieve pending task: `task = PlanMemoryTool.get_next_pending_task()`
+  b) Use `ReasoningTools.think()` to determine which agent to dispatch to
+  c) Dispatch to appropriate agent (Market/News/Social) with proper parameters
+  d) Receive agent's structured report (JSON or Text)
+  e) Parse the report using "AGENT OUTPUT SCHEMAS" section
+  f) Use `ReasoningTools.analyze()` to evaluate data quality, freshness, completeness
+  g) Update task status: `PlanMemoryTool.update_task_status(task_name=task['name'], status='completed' or 'failed', result='meaningful summary with key data/errors')`
+     - ✅ Good result: "BTC Price: $67,543 from Binance at 2025-10-30 14:23:00"
+     - ❌ Bad result: "Done" or "Success"
+  h) Store retrieved data with metadata (timestamp, source, completeness)
+  i) Check data quality and recency using reasoning tools
    
-4.  **Retry Logic (ALWAYS)**
+5.  **Retry Logic (ALWAYS)**
      - If task failed:
+        → Use `ReasoningTools.analyze()` to determine why it failed and best retry strategy
        → MANDATORY retry with modified parameters (max 3 total attempts per objective)
        → Try broader parameters (e.g., wider date range, different keywords, alternative APIs)
        → Try narrower parameters if broader failed
+        → Add new retry task: `PlanMemoryTool.add_tasks(["Retry: Fetch BTC price with broader date range"])` 
        → Never give up until max retries exhausted
-      - Log each retry attempt with reason for parameter change
+      - Log each retry attempt in task result with reason for parameter change
      - Only mark task as permanently failed after all retries exhausted
+      - Update original task status with failure details

-5.  **Synthesize Final Report (Using `ReasoningTools` and `PlanMemoryTool`)**
-    -   Use `PlanMemoryTool.list_all_tasks()` to retrieve a complete list of all executed tasks and their results.
-    -   Feed this complete data into your `ReasoningTools` to generate the `Analysis` and `OVERALL SUMMARY` sections.
-    -   Aggregate data into OUTPUT STRUCTURE.
-    -   Use the output of `PlanMemoryTool.list_all_tasks()` to populate the `EXECUTION LOG & METADATA` section.
+6.  **Synthesize Final Report (MANDATORY Tool Usage)**
+    a) Retrieve all execution data: `all_tasks = PlanMemoryTool.list_all_tasks()`
+    b) Use `ReasoningTools.analyze()` to evaluate overall data quality and completeness
+    c) Use `ReasoningTools.think()` to synthesize findings across Market/News/Social data
+    d) Generate Analysis sections from reasoning tool outputs (not from memory)
+    e) Populate EXECUTION LOG & METADATA from `all_tasks` output
+    f) Aggregate into OUTPUT STRUCTURE with all timestamps and sources preserved

 **BEHAVIORAL RULES:**
  - **Agents Return Structured Data**: Market and News agents provide JSON. SocialAgent provides structured text. Use the "AGENT OUTPUT SCHEMAS" section to parse these.
  - **Tool-Driven State (CRITICAL)**: You are *stateful*. You MUST use `PlanMemoryTool` for ALL plan operations. `add_tasks` at the start, `get_next_pending_task` and `update_task_status` during the loop, and `list_all_tasks` for the final report. Do not rely on context memory alone to track your plan.
  - **Synthesis via Tools (CRITICAL)**: Do not just list data. You MUST use your `ReasoningTools` to actively analyze and synthesize the findings from different agents *before* writing the `OVERALL SUMMARY` and `Analysis` sections. Your analysis *is* the output of this reasoning step.
+  - **Symbol Resolution (MANDATORY)**: When user mentions cryptocurrency names (Bitcoin, Ethereum, etc.), ALWAYS use `CryptoSymbolsTools.get_symbols_by_name()` first to resolve to proper trading symbols before calling MarketAgent. Never assume "Bitcoin" = "BTC" - verify first.
+  - **Handle Symbol Ambiguity**: If `get_symbols_by_name()` returns multiple matches, use `ReasoningTools.think()` to decide or ask user for clarification. Example: "bitcoin" matches both "Bitcoin" and "Bitcoin Cash".
+  - **Symbol Format Awareness**: CryptoSymbolsTools returns Yahoo format ("BTC-USD"). Some market APIs need base symbol only. Strip suffix if needed: `symbol.split('-')[0]`
  - **CRITICAL - Market Data is Sacred**:
      - NEVER modify, round, or summarize price data from MarketAgent.
      - Use the MarketAgent schema to extract ALL numerical values (e.g., `Current Price`, `Detailed Data` prices) and timestamps EXACTLY.
@@ -231,6 +273,45 @@ Execution Notes:
 Timestamp: Report generated at {{CURRENT_DATE}}
 ```

+**COMPLETE WORKFLOW EXAMPLE:**
+
+```
+User Query: "What's the price of Bitcoin and analyze market sentiment?"
+
+Step 1: Symbol Resolution
+think(title="Resolve cryptocurrency name", thought="User said 'Bitcoin', need to find trading symbol", action="search_symbol", confidence=0.95)
+matches = get_symbols_by_name("bitcoin")
+# Returns: [("BTC-USD", "Bitcoin USD")]
+symbol = "BTC-USD"
+
+Step 2: Plan Creation
+think(title="Plan execution", thought="Need price data and sentiment analysis", action="create_comprehensive_plan", confidence=0.9)
+add_tasks([
+    "Fetch BTC-USD current price from market APIs",
+    "Analyze Bitcoin news sentiment from last 24 hours (limit=20)",
+    "Check Bitcoin social media discussions (limit=10)"
+])
+
+Step 3: Execute Tasks
+task = get_next_pending_task()
+# task['name'] = "Fetch BTC-USD current price from market APIs"
+
+# Delegate to MarketAgent...
+market_data = MarketAgent.get_product("BTC-USD")
+analyze(title="Market data quality", result="Received BTC price: $67,543", analysis="Fresh data from Binance", next_action="continue", confidence=0.95)
+update_task_status(task['name'], "completed", "BTC Price: $67,543 from Binance at 2025-10-30 14:23:00")
+
+# Continue with remaining tasks...
+
+Step 4: Synthesis
+all_tasks = list_all_tasks()
+analyze(title="Data synthesis", result="All 3 tasks completed", analysis="Market: $67,543, News: Bullish, Social: Positive", next_action="generate_report", confidence=0.9)
+think(title="Final analysis", thought="Price stable, sentiment positive across sources", action="write_comprehensive_report", confidence=0.92)
+
+Step 5: Generate Report
+# Write report using OUTPUT STRUCTURE with all timestamps and sources
+```
+
 **CRITICAL REMINDERS:**

 1.  Data from agents is ALWAYS current (today is {{CURRENT_DATE}})
@@ -238,4 +319,8 @@ Timestamp: Report generated at {{CURRENT_DATE}}
 3.  If no data for a section, OMIT it entirely (don't write "No data available")
 4.  Track and report data freshness explicitly
 5.  Don't invent or recall old information - only use agent outputs
-6.  **Reference "AGENT OUTPUT SCHEMAS"** for all parsing.
+6.  **Reference "AGENT OUTPUT SCHEMAS"** for all parsing
+7.  **ALWAYS use CryptoSymbolsTools** before calling MarketAgent with cryptocurrency names
+8.  **ALWAYS use PlanMemoryTool** for state management - never rely on memory alone
+9.  **ALWAYS use ReasoningTools** before synthesis - your analysis IS reasoning output
+10. **Task results must be meaningful** - include actual data, not just "Done" or "Success"
--- a/src/app/agents/prompts/team_market.md
+++ b/src/app/agents/prompts/team_market.md
@@ -12,21 +12,69 @@
 **TASK:** Retrieve cryptocurrency price data based on user requests.

 **PARAMETERS:**
- **Asset ID**: Convert common names to tickers (Bitcoin → BTC, Ethereum → ETH)
- **Time Range**: Parse user request (e.g., "last 7 days", "past month", "today")
+- **Asset ID Conversion** (CRITICAL - Always convert common name to tickers):
+  * Bitcoin → BTC
+  * Ethereum → ETH
+  * Solana → SOL
+  * Cardano → ADA
+  * Ripple → XRP
+  * Polkadot → DOT
+  * Dogecoin → DOGE
+- **Time Range Interpretation**:
+  * "last 7 days" / "past week" → limit=7
+  * "last 30 days" / "past month" → limit=30
+  * "last 24 hours" / "today" → limit=1
+  * "last 3 months" → limit=90
 - **Interval**: Determine granularity (hourly, daily, weekly) from context
 - **Defaults**: If not specified, use current price or last 24h data

-**TOOL DESCRIPTIONS:**
- get_product: Fetches current price for a specific cryptocurrency from a single source.
- get_historical_price: Retrieves historical price data for a cryptocurrency over a specified time range from a single source.
- get_products_aggregated: Fetches current prices by aggregating data from multiple sources. Use this if user requests more specific or reliable data.
- get_historical_prices_aggregated: Retrieves historical price data by aggregating multiple sources. Use this if user requests more specific or reliable data.
+**AVAILABLE TOOLS (6 total):**
+
+**SINGLE-SOURCE TOOLS (FAST - Use by default for quick queries):**
+1. **get_product(asset_id: str)** → ProductInfo
+   - Fetches current price for ONE asset from first available provider
+   - Example: get_product("BTC")
+   - Use when: Quick price check for single asset
+
+2. **get_products(asset_ids: list[str])** → list[ProductInfo]
+   - Fetches current prices for MULTIPLE assets from first available provider
+   - Example: get_products(["BTC", "ETH", "SOL"])
+   - Use when: Quick prices for multiple assets
+
+3. **get_historical_prices(asset_id: str, limit: int)** → list[Price]
+   - Fetches historical data for ONE asset from first available provider
+   - Example: get_historical_prices("BTC", limit=7) for last 7 days
+   - Use when: Price history needed (7 days → limit=7, 30 days → limit=30)
+
+**AGGREGATED TOOLS (COMPREHENSIVE - Use only when explicitly requested):**
+4. **get_product_aggregated(asset_id: str)** → ProductInfo
+   - Queries ALL providers (Binance, YFinance, Coinbase, CryptoCompare) and aggregates using VWAP
+   - Returns most accurate/reliable price
+   - Use when: User requests "accurate", "reliable", "comprehensive", "from all sources"
+   - Warning: Uses 4x API calls
+
+5. **get_products_aggregated(asset_ids: list[str])** → list[ProductInfo]
+   - Queries ALL providers for multiple assets and aggregates
+   - Use when: User requests detailed/comprehensive multi-asset analysis
+   - Warning: Uses 4x API calls per asset
+
+6. **get_historical_prices_aggregated(asset_id: str, limit: int)** → list[Price]
+   - Queries ALL providers for historical data and aggregates
+   - Use when: User requests comprehensive historical analysis
+   - Warning: Uses 4x API calls
+
+**TOOL SELECTION STRATEGY:**
+- "What's BTC price?" → get_product("BTC") [#1]
+- "Get accurate BTC price" → get_product_aggregated("BTC") [#4]
+- "Compare BTC, ETH, SOL" → get_products(["BTC", "ETH", "SOL"]) [#2]
+- "Detailed analysis of BTC and ETH" → get_products_aggregated(["BTC", "ETH"]) [#5]
+- "BTC price last week" → get_historical_prices("BTC", limit=7) [#3]
+- "Comprehensive BTC history" → get_historical_prices_aggregated("BTC", limit=30) [#6]

 **OUTPUT FORMAT JSON:**

 **Current Price Request:**
-```
+```json
 {
    Asset: [TICKER]
    Current Price: $[PRICE]
@@ -36,7 +84,7 @@
 ```

 **Historical Data Request:**
-```
+```json
 {
    "Asset": "[TICKER]",
    "Period": {
@@ -62,8 +110,12 @@
 4. **Report data completeness**: If user asks for 30 days but got 7, state this explicitly
 5. **Current date context**: Remind that data is as of {{CURRENT_DATE}}
 6. **Token Optimization**: Be extremely concise to save tokens. Provide all necessary data using as few words as possible. Exceed 100 words ONLY if absolutely necessary to include all required data points.
+7. **Aggregation indicator**: In aggregated results, the 'provider' field shows which sources were used
+8. **Currency**: All prices are typically in USD unless specified otherwise

 **ERROR HANDLING:**
- Tools failed → "Price data unavailable. Error: [details if available]"
+- All providers fail → "Price data unavailable from all sources. Error: [details if available]"
 - Partial data → Report what was retrieved + note missing portions
 - Wrong asset → "Unable to find price data for [ASSET]. Check ticker symbol."
+- API rate limits → Try single-source tools instead of aggregated tools
+- Invalid asset symbol → Suggest correct ticker or similar assets
--- a/src/app/agents/prompts/team_news.md
+++ b/src/app/agents/prompts/team_news.md
@@ -11,15 +11,52 @@
 **TASK:** Retrieve recent crypto news and analyze sentiment to identify market mood and key themes.

 **PARAMETERS:**
- **Query**: Target specific crypto (Bitcoin, Ethereum) or general crypto market
- **Limit**: Number of articles (default: 5, adjust based on request)
+- **Query Formulation** (for search tools):
+  * User: "Bitcoin regulation" → query="Bitcoin regulation"
+  * User: "ETH price surge" → query="Ethereum price increase"
+  * User: "Crypto market crash" → query="cryptocurrency market crash"
+  * User: "NFT trends" → query="NFT trends"
+  * User: "DeFi security" → query="DeFi security vulnerabilities"
+  * Always use full names (Bitcoin not BTC) in search queries
+- **Limit Guidelines**:
+  * Quick overview: limit=5-10
+  * Standard scan: limit=20-30
+  * Deep research: limit=50-100
 - **Recency**: Prioritize most recent articles (last 24-48h preferred)

-**TOOL DESCRIPTION:**
- get_top_headlines: Fetches top cryptocurrency news headlines from a single source.
- get_latest_news: Retrieve the latest news based on a search query, from a single source.
- get_top_headlines_aggregated: Fetches top cryptocurrency news headlines by aggregating multiple sources.
- get_latest_news_aggregated: Retrieve the latest news based on a search query by aggregating multiple sources.
+**AVAILABLE TOOLS (4 total):**
+
+**SINGLE-SOURCE TOOLS (FAST - Use by default for quick queries):**
+1. **get_top_headlines(limit: int)** → list[Article]
+   - Fetches top crypto headlines from first available provider (NewsAPI, Google News, CryptoPanic, DuckDuckGo)
+   - Example: get_top_headlines(limit=10)
+   - Use when: Quick overview of current crypto news
+   - Returns: Articles with title, source, url, published date
+
+2. **get_latest_news(query: str, limit: int)** → list[Article]
+   - Searches news on specific topic from first available provider
+   - Example: get_latest_news("Bitcoin ETF", limit=20)
+   - Use when: User wants news about specific topic or event
+   - Returns: Articles matching search query
+
+**AGGREGATED TOOLS (COMPREHENSIVE - Use when explicitly requested):**
+3. **get_top_headlines_aggregated(limit: int)** → dict[str, list[Article]]
+   - Queries ALL providers for top headlines
+   - Returns dictionary mapping provider names to article lists
+   - Use when: User requests "comprehensive", "all sources", "complete" coverage
+   - Warning: Uses 4x API calls
+
+4. **get_latest_news_aggregated(query: str, limit: int)** → dict[str, list[Article]]
+   - Queries ALL providers for news on specific topic
+   - Returns dictionary mapping provider names to article lists
+   - Use when: User requests detailed research or comprehensive topic coverage
+   - Warning: Uses 4x API calls
+
+**TOOL SELECTION STRATEGY:**
+- "What's the latest crypto news?" → get_top_headlines(limit=10) [#1]
+- "Find news about Bitcoin" → get_latest_news("Bitcoin", limit=20) [#2]
+- "Get all sources for crypto news" → get_top_headlines_aggregated(limit=10) [#3]
+- "Research Ethereum from all sources" → get_latest_news_aggregated("Ethereum", limit=15) [#4]


 **ANALYSIS REQUIREMENTS (if articles found):**
@@ -37,7 +74,7 @@

 **OUTPUT FORMAT:**

-```
+```json
 {
    "News Analysis Summary": {
        "Date": "{{CURRENT_DATE}}",
@@ -86,8 +123,13 @@
 4. **Cite sources**: Mention which news APIs provided the data
 5. **Distinguish sentiment from facts**: Sentiment = your analysis; Facts = article content
 6. **Token Optimization**: Be extremely concise to save tokens. Provide all necessary data using as few words as possible. Exceed 100 words ONLY if absolutely necessary to include all required data points.
+7. **Include article URLs** for user verification when possible
+8. **Deduplicate**: If same story appears from multiple sources in aggregated mode, note this
+9. **Article structure**: Each article contains title, source, url, published_at, description (when available)

 **ERROR HANDLING:**
- No articles found → "No relevant news articles found for [QUERY]"
+- No articles found → "No relevant news articles found for [QUERY]. Try broader search terms."
 - API errors → "Unable to fetch news. Error: [details if available]"
 - Old data → "Warning: Most recent article is from [DATE], may not reflect current sentiment"
+- All providers fail → "News data unavailable from all sources"
+- Partial failure in aggregated mode → Report available sources and note which failed
--- a/src/app/agents/prompts/team_social.md
+++ b/src/app/agents/prompts/team_social.md
@@ -12,12 +12,50 @@

 **PARAMETERS:**
 - **Query**: Target crypto (Bitcoin, Ethereum) or general crypto space
- **Limit**: Number of posts (default: 5, adjust based on request)
- **Platforms**: Reddit (r/cryptocurrency, r/bitcoin), X/Twitter, 4chan /biz/
+- **Limit Guidelines** (posts are LONG - use smaller limits than news):
+  * Quick snapshot: limit=5 (default)
+  * Standard overview: limit=10-15
+  * Deep analysis: limit=20-30
+  * Maximum recommended: limit=50 (to avoid token overflow)
+- **Platform Sources**:
+  * Reddit: r/cryptocurrency, r/bitcoin, r/ethereum, etc.
+  * X (Twitter): High-engagement crypto tweets
+  * 4chan: /biz/ board crypto discussions
+  * Different platforms have different engagement metrics (upvotes, likes, replies)

-**TOOL DESCRIPTIONS:**
- get_top_crypto_posts: Retrieve top cryptocurrency-related posts, optionally limited by the specified number.
- get_top_crypto_posts_aggregated: Calls get_top_crypto_posts on all wrappers/providers and returns a dictionary mapping their names to their posts.
+**AVAILABLE TOOLS (2 total):**
+
+**SINGLE-SOURCE TOOLS (FAST - Use by default):**
+1. **get_top_crypto_posts(limit: int)** → list[SocialPost]
+   - Fetches top crypto posts from first available platform (Reddit, X/Twitter, 4chan)
+   - Example: get_top_crypto_posts(limit=10)
+   - Use when: Quick snapshot of social media sentiment
+   - Returns: SocialPost objects with content, author, engagement metrics
+   - Default limit=5 (posts are long, use small limits)
+
+**AGGREGATED TOOLS (COMPREHENSIVE - Use when explicitly requested):**
+2. **get_top_crypto_posts_aggregated(limit_per_wrapper: int)** → dict[str, list[SocialPost]]
+   - Queries ALL platforms for top crypto posts
+   - Returns dictionary mapping platform names to post lists
+   - Use when: User requests "all platforms", "comprehensive", "complete" social analysis
+   - Warning: Uses 3x API calls (Reddit + X + 4chan)
+
+**TOOL SELECTION STRATEGY:**
+- "What's trending in crypto?" → get_top_crypto_posts(limit=10) [#1]
+- "Show top crypto posts" → get_top_crypto_posts(limit=5) [#1]
+- "Get sentiment from all platforms" → get_top_crypto_posts_aggregated(limit_per_wrapper=10) [#2]
+- "Compare Reddit and Twitter" → get_top_crypto_posts_aggregated(limit_per_wrapper=15) [#2]
+
+**SOCIALPOST STRUCTURE:**
+Each SocialPost contains:
+- content: Post text/message
+- author: Username/handle
+- platform: Source (Reddit, X, 4chan)
+- url: Link to original post
+- created_at: Timestamp
+- score/upvotes: Engagement metric
+- comments_count: Number of replies
+- subreddit/board: Specific community

 **ANALYSIS REQUIREMENTS (if posts found):**

@@ -39,7 +77,7 @@

 **OUTPUT FORMAT:**

-```
+```markdown
 Social Sentiment Analysis ({{CURRENT_DATE}})

 Community Sentiment: [Bullish/Neutral/Bearish]
@@ -67,10 +105,16 @@ Sample Posts (representative):
 3. **Report data staleness**: If newest post is >2 days old, flag this
 4. **Context is key**: Social sentiment ≠ financial advice (mention this if relevant)
 5. **Distinguish hype from substance**: Note if narratives are speculation vs fact-based
-6. **Token Optimization**: Be extremely concise to save tokens. Provide all necessary data using as few words as possible. Exceed 100 words ONLY if absolutely necessary to include all required data points.
+6. **Token Optimization**: Be EXTREMELY concise - social posts are verbose. Summarize trends rather than listing all posts verbatim. Exceed 100 words ONLY if absolutely necessary.
+7. **Include post URLs** for verification when possible
+8. **Misinformation warning**: Social media may contain unverified info, speculation, rumors, shilling
+9. **Content warnings**: 4chan may contain inappropriate language
+10. **Truncate long posts**: Max 280 chars per post excerpt recommended

 **ERROR HANDLING:**
 - No posts found → "No relevant social discussions found for [QUERY]"
 - API errors → "Unable to fetch social data. Error: [details if available]"
 - Old data → "Warning: Most recent post is from [DATE], may not reflect current sentiment"
 - Platform-specific issues → "Reddit data unavailable, analysis based on X and 4chan only"
+- All platforms fail → "Social media data unavailable from all sources"
+- Partial failure in aggregated mode → Report available platforms and note which failed
--- a/src/app/api/tools/instructions/market_instructions.txt
+++ b/src/app/api/tools/instructions/market_instructions.txt
--- a/src/app/api/tools/instructions/news_instructions.md
+++ b/src/app/api/tools/instructions/news_instructions.md
@@ -0,0 +1,98 @@
+News APIs Toolkit - Usage Instructions
+
+OVERVIEW:
+This toolkit provides access to cryptocurrency and general news articles from multiple providers (NewsAPI, Google News, CryptoPanic, DuckDuckGo). You can query a single provider for fast results or aggregate data from all providers for comprehensive coverage.
+
+AVAILABLE TOOLS (4 total):
+
+=== SINGLE-SOURCE TOOLS (FAST) ===
+These tools query providers sequentially and return data from the first one that responds successfully.
+
+1. get_top_headlines(limit: int = 100) → list[Article]
+   - Fetches top cryptocurrency headlines from the first available provider
+   - Example: get_top_headlines(limit=10)
+   - Use when: User wants a quick overview of current crypto news
+   - Returns: List of Article objects with title, source, url, published date
+
+2. get_latest_news(query: str, limit: int = 100) → list[Article]
+   - Searches for news articles on a specific topic
+   - Example: get_latest_news("Bitcoin ETF", limit=20)
+   - Use when: User wants news about a specific topic or event
+   - Returns: List of Article objects matching the search query
+
+=== AGGREGATED TOOLS (COMPREHENSIVE) ===
+These tools query ALL configured providers and return results from each source for maximum coverage.
+
+3. get_top_headlines_aggregated(limit: int = 100) → dict[str, list[Article]]
+   - Queries ALL providers for top headlines
+   - Returns dictionary mapping provider names to their article lists
+   - Example: get_top_headlines_aggregated(limit=15)
+   - Use when: User requests "comprehensive", "all sources", or "complete" news coverage
+   - Warning: Uses 4x API calls (one per provider)
+
+4. get_latest_news_aggregated(query: str, limit: int = 100) → dict[str, list[Article]]
+   - Queries ALL providers for news on a specific topic
+   - Returns dictionary mapping provider names to their article lists
+   - Example: get_latest_news_aggregated("Ethereum merge", limit=20)
+   - Use when: User requests detailed research or comprehensive topic coverage
+   - Warning: Uses 4x API calls
+
+TOOL SELECTION STRATEGY:
+- "What's the latest crypto news?" → get_top_headlines(limit=10) [tool #1]
+- "Find news about Bitcoin" → get_latest_news("Bitcoin", limit=20) [tool #2]
+- "Get all sources for crypto news" → get_top_headlines_aggregated(limit=10) [tool #3]
+- "Research Ethereum from all sources" → get_latest_news_aggregated("Ethereum", limit=15) [tool #4]
+
+QUERY FORMULATION:
+When users ask about specific topics, construct clear search queries:
+- "Bitcoin regulation" → query="Bitcoin regulation"
+- "ETH price surge" → query="Ethereum price increase"
+- "Crypto market crash" → query="cryptocurrency market crash"
+- "NFT trends" → query="NFT trends"
+- "DeFi security" → query="DeFi security vulnerabilities"
+
+ARTICLE STRUCTURE:
+Each Article object typically contains:
+- title: Article headline
+- source: Publication/website name
+- url: Link to full article
+- published_at: Publication timestamp
+- description: Article summary (when available)
+- author: Article author (when available)
+
+LIMIT GUIDELINES:
+- Quick overview: limit=5-10
+- Standard news scan: limit=20-30
+- Deep research: limit=50-100
+- Each provider respects the limit independently in aggregated mode
+
+CRITICAL RULES:
+1. NEVER fabricate news articles or headlines - only report actual tool outputs
+2. ALL articles returned by tools are REAL and from actual news sources
+3. ALWAYS include article source and publication date when available
+4. ALWAYS include article URLs so users can verify information
+5. If tools fail, report the failure explicitly - DO NOT invent placeholder articles
+6. In aggregated results, clearly separate articles by provider
+
+ERROR HANDLING:
+- All providers fail → Report "News data unavailable from all sources"
+- Partial data → Report available articles and note which sources failed
+- No results for query → Report "No news articles found for '[QUERY]'. Try broader terms"
+- API rate limits → Try single-source tools instead of aggregated tools
+
+OUTPUT REQUIREMENTS:
+- Include article title (required)
+- Include source/publication name (required)
+- Include URL for verification (required)
+- Include publication date/time when available
+- Provide brief summary/description when available
+- Group articles by source in aggregated mode
+- Be concise to save tokens - focus on headlines and key info
+- Deduplicate articles when same story appears from multiple sources
+
+SEARCH BEST PRACTICES:
+- Use specific keywords for focused results
+- Use broader terms if no results found
+- Include cryptocurrency names in full (Bitcoin not just BTC)
+- Consider alternative spellings or synonyms
+- Avoid overly technical jargon in queries
--- a/src/app/api/tools/instructions/plan_memory_instructions.md
+++ b/src/app/api/tools/instructions/plan_memory_instructions.md
@@ -0,0 +1,305 @@
+# Plan Memory Tool - Usage Instructions
+
+## OVERVIEW
+This toolkit provides stateful, persistent memory for the Team Leader agent. It functions as your primary to-do list and state tracker, enabling you to create, execute step-by-step, and record the results of your execution plan.
+
+## PURPOSE
+- **Task Management**: Create and track execution plans with multiple steps
+- **State Persistence**: Maintain execution state across multiple agent calls
+- **Progress Tracking**: Monitor which tasks are pending, completed, or failed
+- **Result Recording**: Store outcomes and results for each executed task
+
+## AVAILABLE TOOLS (4 total)
+
+### 1. **add_tasks(task_names: list[str])** → str
+Adds one or more new tasks to the execution plan with 'pending' status.
+
+**Behavior:**
+- If a task with the same name already exists, it will NOT be added again (prevents duplicates)
+- All new tasks start with status='pending' and result=None
+- Tasks are added to the end of the task list
+
+**Arguments:**
+- `task_names` (list[str]): List of descriptive names for tasks to add
+
+**Returns:**
+- Confirmation message: "Added N new tasks."
+
+**Example Usage:**
+```python
+add_tasks([
+    "Fetch Bitcoin price data",
+    "Analyze market sentiment from news",
+    "Retrieve social media discussions",
+    "Generate comprehensive report"
+])
+# Returns: "Added 4 new tasks."
+```
+
+**Best Practices:**
+- Use clear, descriptive task names that explain what needs to be done
+- Break complex operations into smaller, manageable tasks
+- Order tasks logically (dependencies first)
+- Include specific details in task names (e.g., "Fetch BTC price for last 7 days" not "Get price")
+
+---
+
+### 2. **get_next_pending_task()** → Task | None
+Retrieves the FIRST task from the plan that has 'pending' status.
+
+**Behavior:**
+- Returns tasks in the order they were added (FIFO - First In, First Out)
+- Only returns tasks with status='pending'
+- Returns None if no pending tasks exist
+
+**Returns:**
+- Task object (dict) with keys:
+  - `name` (str): Task name
+  - `status` (str): Always "pending" when returned by this function
+  - `result` (str | None): Always None for pending tasks
+- None if no pending tasks
+
+**Example Usage:**
+```python
+next_task = get_next_pending_task()
+if next_task:
+    print(f"Next task to execute: {next_task['name']}")
+else:
+    print("All tasks completed or no tasks in plan")
+```
+
+**Workflow Pattern:**
+1. Call `get_next_pending_task()` to get next task
+2. Execute the task using appropriate specialist agent/tool
+3. Call `update_task_status()` with results
+4. Repeat until `get_next_pending_task()` returns None
+
+---
+
+### 3. **update_task_status(task_name: str, status: Literal["completed", "failed"], result: str | None)** → str
+Updates the status and result of a specific task after execution.
+
+**Arguments:**
+- `task_name` (str): Exact name of the task (must match name from add_tasks)
+- `status` (str): New status - either "completed" or "failed"
+- `result` (str | None): Optional description of outcome, error message, or summary
+
+**Returns:**
+- Success: "Task 'Task Name' updated to {status}."
+- Error: "Error: Task 'Task Name' not found."
+
+**Example Usage:**
+```python
+# After successfully executing a task:
+update_task_status(
+    task_name="Fetch Bitcoin price data",
+    status="completed",
+    result="Retrieved BTC price: $67,543 from Binance at 2025-10-30 14:23:00"
+)
+
+# After task failure:
+update_task_status(
+    task_name="Analyze market sentiment",
+    status="failed",
+    result="Error: News API rate limit exceeded. Unable to fetch articles."
+)
+```
+
+**Best Practices:**
+- Always update status immediately after task execution
+- Provide meaningful results that can be referenced later
+- Include key data in result (prices, counts, timestamps)
+- For failures, include error details for debugging
+- Keep results concise but informative
+
+---
+
+### 4. **list_all_tasks()** → list[str]
+Lists all tasks in the execution plan with their status and results.
+
+**Returns:**
+- List of formatted strings, each describing one task
+- Format: "- {task_name}: {status} (Result: {result})"
+- Returns ["No tasks in the plan."] if task list is empty
+
+**Example Output:**
+```
+[
+    "- Fetch Bitcoin price data: completed (Result: BTC=$67,543 at 14:23:00)",
+    "- Analyze market sentiment: completed (Result: Bullish sentiment, 15 articles)",
+    "- Retrieve social media posts: pending (Result: N/A)",
+    "- Generate report: pending (Result: N/A)"
+]
+```
+
+**Use Cases:**
+- Review overall plan progress
+- Check which tasks remain pending
+- Retrieve results from completed tasks
+- Debug failed tasks
+- Provide status updates to user
+
+---
+
+## WORKFLOW PATTERNS
+
+### **Pattern 1: Simple Sequential Execution**
+```python
+# Step 1: Create plan
+add_tasks(["Task A", "Task B", "Task C"])
+
+# Step 2: Execute loop
+while True:
+    task = get_next_pending_task()
+    if not task:
+        break
+    
+    # Execute task...
+    result = execute_task(task['name'])
+    
+    # Update status
+    update_task_status(task['name'], "completed", result)
+
+# Step 3: Review results
+all_tasks = list_all_tasks()
+```
+
+### **Pattern 2: Conditional Execution**
+```python
+add_tasks(["Fetch data", "Analyze if data available", "Generate report"])
+
+task = get_next_pending_task()
+result = fetch_data()
+
+if result is None:
+    update_task_status("Fetch data", "failed", "No data available")
+    # Skip remaining tasks or add alternative tasks
+else:
+    update_task_status("Fetch data", "completed", result)
+    # Continue to next task
+```
+
+### **Pattern 3: Dynamic Task Addition**
+```python
+add_tasks(["Check user request type"])
+
+task = get_next_pending_task()
+request_type = analyze_request()
+
+if request_type == "comprehensive":
+    # Add detailed tasks for comprehensive analysis
+    add_tasks([
+        "Fetch from all providers",
+        "Aggregate results",
+        "Perform cross-validation"
+    ])
+else:
+    # Add simple tasks for quick lookup
+    add_tasks(["Fetch from single provider"])
+
+update_task_status("Check user request type", "completed", f"Type: {request_type}")
+```
+
+---
+
+## CRITICAL RULES
+
+1. **Task Names Must Be Unique**: Don't add duplicate task names - they will be ignored
+2. **Exact Name Matching**: When updating status, task_name must EXACTLY match the name used in add_tasks
+3. **Update After Execution**: ALWAYS call update_task_status after executing a task
+4. **Sequential Execution**: Execute tasks in order using get_next_pending_task()
+5. **Meaningful Results**: Store actionable information in results, not just "Done" or "Success"
+6. **Handle Failures**: Don't stop plan execution when a task fails - update status and continue or adapt plan
+7. **Review Before Finishing**: Call list_all_tasks() before completing user request to verify all tasks executed
+
+---
+
+## TASK NAMING BEST PRACTICES
+
+**Good Task Names:**
+- ✅ "Fetch BTC price from Binance for last 7 days"
+- ✅ "Analyze news sentiment for Ethereum"
+- ✅ "Retrieve Reddit posts about DeFi (limit=10)"
+- ✅ "Calculate VWAP from aggregated provider data"
+- ✅ "Generate comparison report for BTC vs ETH"
+
+**Poor Task Names:**
+- ❌ "Get data" (too vague)
+- ❌ "Step 1" (not descriptive)
+- ❌ "Do analysis" (what kind of analysis?)
+- ❌ "Fetch" (fetch what?)
+
+---
+
+## RESULT CONTENT GUIDELINES
+
+**Good Results:**
+- ✅ "BTC price: $67,543 (Binance, 2025-10-30 14:23:00)"
+- ✅ "Analyzed 15 articles. Sentiment: Bullish. Key theme: ETF approval"
+- ✅ "Retrieved 10 Reddit posts. Avg upvotes: 234. Trend: Positive on BTC"
+- ✅ "Aggregated 3 providers: Binance, Coinbase, YFinance. VWAP: $67,521"
+
+**Poor Results:**
+- ❌ "Done"
+- ❌ "Success"
+- ❌ "OK"
+- ❌ "Completed successfully"
+
+---
+
+## ERROR HANDLING
+
+**Common Errors:**
+1. **Task Not Found**: Task name doesn't match exactly
+   - Solution: Check spelling, capitalization, and spacing
+   
+2. **No Pending Tasks**: get_next_pending_task() returns None
+   - Solution: Verify tasks were added, check if all are completed/failed
+   
+3. **Duplicate Task Names**: Task not added because name exists
+   - Solution: Use unique, descriptive names or update existing task
+
+**Recovery Strategies:**
+- If specialist agent fails, mark task as "failed" with error details
+- Add alternative tasks to work around failures
+- Continue execution with remaining tasks
+- Provide partial results if some tasks completed
+
+---
+
+## INTEGRATION WITH SPECIALIST AGENTS
+
+When delegating to specialist agents (Market, News, Social), follow this pattern:
+
+```python
+# 1. Create plan
+add_tasks([
+    "Fetch market data for BTC",
+    "Analyze news sentiment",
+    "Check social media trends"
+])
+
+# 2. Execute market task
+task = get_next_pending_task()
+# Delegate to Market Specialist...
+market_result = market_agent.get_product("BTC")
+update_task_status(task['name'], "completed", f"BTC Price: ${market_result.price}")
+
+# 3. Execute news task
+task = get_next_pending_task()
+# Delegate to News Specialist...
+news_result = news_agent.get_latest_news("Bitcoin", limit=20)
+update_task_status(task['name'], "completed", f"Found {len(news_result)} articles")
+
+# And so on...
+```
+
+---
+
+## STATE PERSISTENCE
+
+**Important Notes:**
+- Task state persists within a single agent session/conversation
+- State is NOT persisted across different sessions or restarts
+- If agent is reset, all tasks are lost
+- For long-running operations, periodically call list_all_tasks() to preserve progress in conversation context
--- a/src/app/api/tools/instructions/social_instructions.md
+++ b/src/app/api/tools/instructions/social_instructions.md
@@ -0,0 +1,110 @@
+Social Media Toolkit - Usage Instructions
+
+OVERVIEW:
+This toolkit provides access to cryptocurrency-related social media posts from multiple platforms (Reddit, X/Twitter, 4chan). You can query a single platform for fast results or aggregate data from all platforms for comprehensive social sentiment analysis.
+
+AVAILABLE TOOLS (2 total):
+
+=== SINGLE-SOURCE TOOLS (FAST) ===
+These tools query platforms sequentially and return data from the first one that responds successfully.
+
+1. get_top_crypto_posts(limit: int = 5) → list[SocialPost]
+   - Fetches top cryptocurrency-related posts from the first available platform
+   - Example: get_top_crypto_posts(limit=10)
+   - Use when: User wants a quick snapshot of social media sentiment
+   - Returns: List of SocialPost objects with content, author, engagement metrics
+   - Default limit is intentionally small (5) due to post length
+
+=== AGGREGATED TOOLS (COMPREHENSIVE) ===
+These tools query ALL configured platforms and return results from each source for complete social coverage.
+
+2. get_top_crypto_posts_aggregated(limit_per_wrapper: int = 5) → dict[str, list[SocialPost]]
+   - Queries ALL platforms for top crypto posts
+   - Returns dictionary mapping platform names to their post lists
+   - Example: get_top_crypto_posts_aggregated(limit_per_wrapper=10)
+   - Use when: User requests "all platforms", "comprehensive", or "complete" social analysis
+   - Warning: Uses 3x API calls (one per platform: Reddit, X, 4chan)
+
+TOOL SELECTION STRATEGY:
+- "What's trending in crypto on social media?" → get_top_crypto_posts(limit=10) [tool #1]
+- "Show top crypto posts" → get_top_crypto_posts(limit=5) [tool #1]
+- "Get crypto sentiment from all platforms" → get_top_crypto_posts_aggregated(limit_per_wrapper=10) [tool #2]
+- "Compare Reddit and Twitter crypto posts" → get_top_crypto_posts_aggregated(limit_per_wrapper=15) [tool #2]
+
+SOCIALPOST STRUCTURE:
+Each SocialPost object typically contains:
+- content: Post text/message
+- author: Username/handle of poster
+- platform: Source platform (Reddit, X, 4chan)
+- url: Link to original post
+- created_at: Post timestamp
+- score/upvotes: Engagement metric (platform-dependent)
+- comments_count: Number of comments/replies
+- subreddit/board: Specific community (Reddit/4chan)
+
+LIMIT GUIDELINES:
+Social media posts are longer than news headlines, so use smaller limits:
+- Quick snapshot: limit=5 (default)
+- Standard overview: limit=10-15
+- Deep analysis: limit=20-30
+- Maximum recommended: limit=50 (to avoid token overflow)
+
+PLATFORM-SPECIFIC NOTES:
+- Reddit: Posts from r/cryptocurrency, r/bitcoin, r/ethereum and similar subreddits
+- X (Twitter): Crypto-related tweets with high engagement
+- 4chan: Posts from /biz/ board focused on crypto discussions
+- Each platform has different engagement metrics (upvotes, likes, replies)
+
+CRITICAL RULES:
+1. NEVER fabricate social media posts - only report actual tool outputs
+2. ALL posts returned by tools are REAL from actual users
+3. ALWAYS include platform source and author information
+4. ALWAYS include post URLs for verification
+5. Be aware of potential misinformation in social media content
+6. If tools fail, report the failure explicitly - DO NOT invent placeholder posts
+7. In aggregated results, clearly separate posts by platform
+8. Social media reflects opinions, not facts - frame accordingly
+
+ERROR HANDLING:
+- All platforms fail → Report "Social media data unavailable from all sources"
+- Partial data → Report available posts and note which platforms failed
+- No crypto posts found → Report "No cryptocurrency posts available at this time"
+- API rate limits → Try single-source tool or reduce limit
+
+OUTPUT REQUIREMENTS:
+- Include post content (truncate if too long, max 280 chars recommended)
+- Include author/username (required)
+- Include platform name (required)
+- Include engagement metrics (upvotes, likes, comments)
+- Include post URL for verification
+- Include timestamp/date when available
+- Group posts by platform in aggregated mode
+- Summarize sentiment trends rather than listing all posts verbatim
+- Be VERY concise to save tokens - social posts are verbose
+
+SENTIMENT ANALYSIS TIPS:
+- Look for recurring topics across posts
+- Note positive vs negative sentiment patterns
+- Identify trending coins or topics
+- Compare sentiment across platforms
+- Highlight posts with high engagement
+- Flag potential FUD (Fear, Uncertainty, Doubt) or shilling
+
+CONTENT WARNINGS:
+- Social media may contain:
+  - Unverified information
+  - Speculation and rumors
+  - Promotional/shilling content
+  - Strong opinions or biased views
+  - Inappropriate language (especially 4chan)
+- Always present social data with appropriate disclaimers
+- Do not treat social media posts as factual evidence
+- Encourage users to verify information from official sources
+
+BEST PRACTICES:
+- Use aggregated tool for sentiment comparison across platforms
+- Combine with news data for context
+- Focus on high-engagement posts for quality
+- Summarize trends rather than listing every post
+- Be selective - quality over quantity
+- Respect character limits to avoid token overflow
--- a/src/app/api/tools/instructions/symbols_instructions.md
+++ b/src/app/api/tools/instructions/symbols_instructions.md
@@ -0,0 +1,352 @@
+# Crypto Symbols Tool - Usage Instructions
+
+## OVERVIEW
+This toolkit provides access to cryptocurrency symbol lookup and search functionality. It maintains a cached database of cryptocurrency symbols from Yahoo Finance, enabling fast symbol resolution and name-based searches.
+
+## PURPOSE
+- **Symbol Lookup**: Get complete list of available cryptocurrency symbols
+- **Name Search**: Find cryptocurrency symbols by searching their names
+- **Symbol Resolution**: Convert common names to trading symbols for use with market data APIs
+- **Cache Management**: Maintains local cache for fast queries without repeated API calls
+
+## AVAILABLE TOOLS (2 total)
+
+### 1. **get_all_symbols()** → list[str]
+Returns a complete list of all cryptocurrency symbols available in the cached database.
+
+**Behavior:**
+- Returns all symbols from the local cache (CSV file)
+- No API calls - instant response
+- Returns empty list if cache is not populated
+
+**Returns:**
+- `list[str]`: List of cryptocurrency symbols (e.g., ["BTC-USD", "ETH-USD", "SOL-USD", ...])
+
+**Example Usage:**
+```python
+all_symbols = get_all_symbols()
+print(f"Total cryptocurrencies available: {len(all_symbols)}")
+# Output: Total cryptocurrencies available: 1523
+
+# Check if specific symbol exists
+if "BTC-USD" in all_symbols:
+    print("Bitcoin is available")
+```
+
+**Use Cases:**
+- Verify if a cryptocurrency is supported before fetching data
+- Get complete list of available assets for comprehensive analysis
+- Validate user input against known symbols
+- Browse all available cryptocurrencies
+
+**Important Notes:**
+- Symbols include suffix (e.g., "BTC-USD" not just "BTC")
+- Cache must be populated first (happens automatically on initialization if cache file exists)
+- Returns snapshot from last cache update, not real-time availability
+
+---
+
+### 2. **get_symbols_by_name(query: str)** → list[tuple[str, str]]
+Searches for cryptocurrency symbols whose names contain the query string (case-insensitive).
+
+**Arguments:**
+- `query` (str): Search term to match against cryptocurrency names
+
+**Returns:**
+- `list[tuple[str, str]]`: List of (symbol, name) tuples matching the query
+- Returns empty list if no matches found
+
+**Example Usage:**
+```python
+# Search for Bitcoin-related cryptocurrencies
+results = get_symbols_by_name("bitcoin")
+# Returns: [("BTC-USD", "Bitcoin USD"), ("BTT-USD", "Bitcoin Token USD"), ...]
+
+# Search for Ethereum
+results = get_symbols_by_name("ethereum")
+# Returns: [("ETH-USD", "Ethereum USD"), ("ETC-USD", "Ethereum Classic USD"), ...]
+
+# Partial name search
+results = get_symbols_by_name("doge")
+# Returns: [("DOGE-USD", "Dogecoin USD"), ...]
+
+# Check if found
+if results:
+    symbol, name = results[0]
+    print(f"Found: {name} with symbol {symbol}")
+else:
+    print("No cryptocurrencies found matching query")
+```
+
+**Search Behavior:**
+- Case-insensitive matching
+- Partial match (substring search)
+- Searches only in the "Name" field, not symbols
+- Returns all matches, not just the first one
+
+**Use Cases:**
+- Convert user-friendly names to trading symbols
+- Handle ambiguous user input ("bitcoin" → multiple results including Bitcoin, Bitcoin Cash, etc.)
+- Discover cryptocurrencies by partial name
+- Validate and suggest corrections for misspelled names
+
+**Best Practices:**
+- Use full or near-full names for precise matches
+- Handle multiple results - ask user to clarify if ambiguous
+- Always check if results list is empty before accessing
+- Display both symbol and name to user for confirmation
+
+---
+
+## SYMBOL FORMAT
+
+**Yahoo Finance Symbol Format:**
+- All symbols include currency suffix: `-USD`
+- Example: `BTC-USD`, `ETH-USD`, `SOL-USD`
+
+**Common Conversions:**
+```
+User Input    →  Search Query       →  Symbol Result
+"Bitcoin"     →  "bitcoin"          →  "BTC-USD"
+"Ethereum"    →  "ethereum"         →  "ETH-USD"
+"Solana"      →  "solana"           →  "SOL-USD"
+"Cardano"     →  "cardano"          →  "ADA-USD"
+"Dogecoin"    →  "dogecoin"         →  "DOGE-USD"
+```
+
+**When Using Symbols with Market APIs:**
+- Some APIs require just the base symbol: `BTC`, `ETH`
+- Some APIs require the full Yahoo format: `BTC-USD`
+- Check individual market API documentation for required format
+- You may need to strip the `-USD` suffix: `symbol.split('-')[0]`
+
+---
+
+## CACHE MANAGEMENT
+
+**Cache File Location:**
+- Default: `resources/cryptos.csv`
+- Contains: Symbol, Name, and other metadata columns
+
+**Cache Initialization:**
+- Cache loaded automatically on tool initialization if file exists
+- If cache file doesn't exist, `get_all_symbols()` returns empty list
+- Cache can be refreshed using `fetch_crypto_symbols(force_refresh=True)` (admin function)
+
+**Cache Contents:**
+- Approximately 1,500+ cryptocurrency symbols
+- Includes major coins (BTC, ETH, SOL) and smaller altcoins
+- Updated periodically from Yahoo Finance
+
+**Performance:**
+- All queries are **instant** - no API calls during normal use
+- Cache lookup is O(1) for get_all_symbols
+- Search is O(n) for get_symbols_by_name but very fast for ~1,500 entries
+
+---
+
+## WORKFLOW PATTERNS
+
+### **Pattern 1: Symbol Validation**
+```python
+# User asks for "Bitcoin" price
+user_query = "bitcoin"
+
+# Search for matching symbols
+matches = get_symbols_by_name(user_query)
+
+if not matches:
+    # No matches found
+    return "Cryptocurrency not found. Please check the name."
+elif len(matches) == 1:
+    # Single match - proceed
+    symbol, name = matches[0]
+    # Use symbol with market API: market_tool.get_product(symbol)
+else:
+    # Multiple matches - ask user to clarify
+    options = "\n".join([f"- {name} ({symbol})" for symbol, name in matches])
+    return f"Multiple matches found:\n{options}\nPlease specify which one."
+```
+
+### **Pattern 2: Symbol Discovery**
+```python
+# User asks "What coins are available?"
+all_symbols = get_all_symbols()
+total_count = len(all_symbols)
+
+# Show sample or summary
+top_10 = all_symbols[:10]
+return f"There are {total_count} cryptocurrencies available. Top 10: {', '.join(top_10)}"
+```
+
+### **Pattern 3: Fuzzy Matching**
+```python
+# User types "etherium" (misspelled)
+query = "etherium"
+matches = get_symbols_by_name(query)
+
+if not matches:
+    # Try alternative spellings
+    alternatives = ["ethereum", "ether"]
+    for alt in alternatives:
+        matches = get_symbols_by_name(alt)
+        if matches:
+            return f"Did you mean {matches[0][1]}? (Symbol: {matches[0][0]})"
+    return "No matches found"
+else:
+    # Found matches
+    return matches
+```
+
+### **Pattern 4: Batch Symbol Resolution**
+```python
+# User asks for multiple cryptocurrencies
+user_requests = ["Bitcoin", "Ethereum", "Solana", "UnknownCoin"]
+resolved_symbols = []
+failed = []
+
+for name in user_requests:
+    matches = get_symbols_by_name(name.lower())
+    if matches:
+        resolved_symbols.append(matches[0][0])  # Take first match
+    else:
+        failed.append(name)
+
+# Now use resolved_symbols with market API
+if resolved_symbols:
+    prices = market_tool.get_products(resolved_symbols)
+    
+if failed:
+    print(f"Warning: Could not find symbols for: {', '.join(failed)}")
+```
+
+---
+
+## INTEGRATION WITH MARKET TOOLS
+
+**Typical Workflow:**
+1. User provides cryptocurrency name (e.g., "Bitcoin", "Ethereum")
+2. Use `get_symbols_by_name()` to find matching symbol
+3. Pass symbol to Market Tool APIs (get_product, get_products, etc.)
+4. Return price data to user
+
+**Example Integration:**
+```python
+# Step 1: User request
+user_input = "Get Bitcoin price"
+
+# Step 2: Extract cryptocurrency name and search
+crypto_name = "bitcoin"  # Extracted from user_input
+matches = get_symbols_by_name(crypto_name)
+
+if not matches:
+    return "Cryptocurrency not found"
+
+symbol, full_name = matches[0]
+
+# Step 3: Fetch price data
+price_data = market_tool.get_product(symbol)
+
+# Step 4: Return result
+return f"{full_name} ({symbol}): ${price_data.price}"
+```
+
+---
+
+## CRITICAL RULES
+
+1. **Always Search Before Using Names**: Never assume a name directly converts to a symbol
+2. **Handle Multiple Matches**: Names like "Bitcoin" might match multiple cryptocurrencies
+3. **Case-Insensitive Search**: Always use lowercase for query consistency
+4. **Check Empty Results**: Always verify search results before accessing
+5. **Symbol Format**: Remember Yahoo symbols have `-USD` suffix
+6. **Cache Dependency**: Tools require cache to be populated (usually automatic)
+
+---
+
+## COMMON USE CASES
+
+### **Use Case 1: Name to Symbol Conversion**
+User says: "What's the price of Cardano?"
+1. Search: `get_symbols_by_name("cardano")`
+2. Get symbol: `"ADA-USD"`
+3. Fetch price: `market_tool.get_product("ADA-USD")`
+
+### **Use Case 2: Symbol Verification**
+User provides: "BTC-USD"
+1. Check: `"BTC-USD" in get_all_symbols()`
+2. If True, proceed with API call
+3. If False, suggest similar names
+
+### **Use Case 3: Discovery**
+User asks: "What cryptos start with 'Sol'?"
+1. Search: `get_symbols_by_name("sol")`
+2. Return all matches (Solana, etc.)
+
+### **Use Case 4: Ambiguity Resolution**
+User says: "Bitcoin"
+1. Search: `get_symbols_by_name("bitcoin")`
+2. Results: `[("BTC-USD", "Bitcoin USD"), ("BCH-USD", "Bitcoin Cash USD"), ...]`
+3. Ask user: "Did you mean Bitcoin (BTC) or Bitcoin Cash (BCH)?"
+
+---
+
+## ERROR HANDLING
+
+**Common Issues:**
+
+1. **Empty Cache**
+   - Symptom: `get_all_symbols()` returns empty list
+   - Cause: Cache file missing or not loaded
+   - Solution: Ensure `resources/cryptos.csv` exists
+
+2. **No Search Results**
+   - Symptom: `get_symbols_by_name()` returns empty list
+   - Cause: Query doesn't match any cryptocurrency names
+   - Solution: Try broader search terms, check spelling, suggest alternatives
+
+3. **Multiple Matches**
+   - Symptom: Search returns many results
+   - Cause: Query is too broad (e.g., "coin")
+   - Solution: Ask user to be more specific, show all matches
+
+4. **Symbol Format Mismatch**
+   - Symptom: Market API fails with Yahoo symbol
+   - Cause: API expects different format
+   - Solution: Strip suffix: `symbol.split('-')[0]` → `"BTC-USD"` becomes `"BTC"`
+
+---
+
+## SEARCH TIPS
+
+**Effective Searches:**
+- ✅ Use full names: "ethereum", "bitcoin", "solana"
+- ✅ Use common names: "ether" finds "Ethereum"
+- ✅ Partial names work: "doge" finds "Dogecoin"
+
+**Ineffective Searches:**
+- ❌ Ticker symbols: "BTC" (search by name, not symbol)
+- ❌ Too generic: "coin", "token" (returns too many results)
+- ❌ Abbreviations: "eth" might not match "Ethereum" (try full name)
+
+**Best Practice:**
+If user provides a ticker symbol (BTC, ETH), first check if it exists in `get_all_symbols()`, then try name search as fallback.
+
+---
+
+## PERFORMANCE NOTES
+
+- **get_all_symbols()**: O(1) - Instant
+- **get_symbols_by_name()**: O(n) - Fast (< 1ms for ~1,500 entries)
+- **No Network Calls**: All data served from local cache
+- **Memory Efficient**: CSV loaded once on initialization
+
+---
+
+## LIMITATIONS
+
+1. **Yahoo Finance Dependency**: Symbol list limited to what Yahoo Finance provides
+2. **No Real-Time Updates**: Cache is static snapshot, not live data
+3. **Name Matching Only**: Cannot search by symbol, market cap, or other criteria
+4. **USD Pairs Only**: Only symbols with `-USD` suffix are included
+5. **No Metadata**: Only symbol and name available, no price, volume, or market cap in this tool
--- a/src/app/api/tools/market_tool.py
+++ b/src/app/api/tools/market_tool.py
@@ -21,7 +21,7 @@ class MarketAPIsTool(MarketWrapper, Toolkit):
        Returns:
            str: The content of the instructions file.
        """
-        instructions_path = Path(__file__).parent / "instructions" / "market_instructions.txt"
+        instructions_path = Path(__file__).parent / "instructions" / "market_instructions.md"
        return instructions_path.read_text(encoding="utf-8")

    def __init__(self):
--- a/src/app/api/tools/news_tool.py
+++ b/src/app/api/tools/news_tool.py
@@ -1,3 +1,4 @@
+from pathlib import Path
 from agno.tools import Toolkit
 from app.api.wrapper_handler import WrapperHandler
 from app.api.core.news import NewsWrapper, Article
@@ -15,6 +16,17 @@ class NewsAPIsTool(NewsWrapper, Toolkit):
    If no wrapper succeeds, an exception is raised.
    """

+    @staticmethod
+    def _load_instructions() -> str:
+        """
+        Load the toolkit instructions from the external text file.
+        
+        Returns:
+            str: The content of the instructions file.
+        """
+        instructions_path = Path(__file__).parent / "instructions" / "news_instructions.md"
+        return instructions_path.read_text(encoding="utf-8")
+
    def __init__(self):
        """
        Initialize the NewsAPIsTool with news API wrappers configured in configs.yaml.
@@ -38,6 +50,7 @@ class NewsAPIsTool(NewsWrapper, Toolkit):
                self.get_top_headlines_aggregated,
                self.get_latest_news_aggregated,
            ],
+            instructions=self._load_instructions(),
        )

    def get_top_headlines(self, limit: int = 100) -> list[Article]:
--- a/src/app/api/tools/plan_memory_tool.py
+++ b/src/app/api/tools/plan_memory_tool.py
@@ -1,3 +1,4 @@
+from pathlib import Path
 from agno.tools.toolkit import Toolkit
 from typing import TypedDict, Literal

@@ -10,12 +11,21 @@ class Task(TypedDict):


 class PlanMemoryTool(Toolkit):
+    @staticmethod
+    def _load_instructions() -> str:
+        """
+        Load the toolkit instructions from the external markdown file.
+        
+        Returns:
+            str: The content of the instructions file.
+        """
+        instructions_path = Path(__file__).parent / "instructions" / "plan_memory_instructions.md"
+        return instructions_path.read_text(encoding="utf-8")
+
    def __init__(self):
        self.tasks: list[Task] = []
        Toolkit.__init__(self, # type: ignore[call-arg]
-            instructions="Provides stateful, persistent memory for the Team Leader. " \
-                 "This is your primary to-do list and state tracker. " \
-                 "Use it to create, execute step-by-step, and record the results of your execution plan.",
+            instructions=self._load_instructions(),
            tools=[
                self.add_tasks,
                self.get_next_pending_task,
--- a/src/app/api/tools/social_tool.py
+++ b/src/app/api/tools/social_tool.py
@@ -1,3 +1,4 @@
+from pathlib import Path
 from agno.tools import Toolkit
 from app.api.wrapper_handler import WrapperHandler
 from app.api.core.social import SocialPost, SocialWrapper
@@ -16,6 +17,17 @@ class SocialAPIsTool(SocialWrapper, Toolkit):
    If no wrapper succeeds, an exception is raised.
    """

+    @staticmethod
+    def _load_instructions() -> str:
+        """
+        Load the toolkit instructions from the external text file.
+        
+        Returns:
+            str: The content of the instructions file.
+        """
+        instructions_path = Path(__file__).parent / "instructions" / "social_instructions.md"
+        return instructions_path.read_text(encoding="utf-8")
+
    def __init__(self):
        """
        Initialize the SocialAPIsTool with social media API wrappers configured in configs.yaml.
@@ -37,6 +49,7 @@ class SocialAPIsTool(SocialWrapper, Toolkit):
                self.get_top_crypto_posts,
                self.get_top_crypto_posts_aggregated,
            ],
+            instructions=self._load_instructions(),
        )

    def get_top_crypto_posts(self, limit: int = 5) -> list[SocialPost]:
--- a/src/app/api/tools/symbols_tool.py
+++ b/src/app/api/tools/symbols_tool.py
@@ -4,6 +4,7 @@ import asyncio
 import logging
 import pandas as pd
 from io import StringIO
+from pathlib import Path
 from agno.tools.toolkit import Toolkit

 logging.basicConfig(level=logging.INFO)
@@ -18,12 +19,23 @@ class CryptoSymbolsTools(Toolkit):
    Classe per ottenere i simboli delle criptovalute tramite Yahoo Finance.
    """

+    @staticmethod
+    def _load_instructions() -> str:
+        """
+        Load the toolkit instructions from the external markdown file.
+        
+        Returns:
+            str: The content of the instructions file.
+        """
+        instructions_path = Path(__file__).parent / "instructions" / "symbols_instructions.md"
+        return instructions_path.read_text(encoding="utf-8")
+
    def __init__(self, cache_file: str = 'resources/cryptos.csv'):
        self.cache_file = cache_file
        self.final_table = pd.read_csv(self.cache_file) if os.path.exists(self.cache_file) else pd.DataFrame() # type: ignore
        Toolkit.__init__(self, # type: ignore
            name="Crypto Symbols Tool",
-            instructions="Tool to get cryptocurrency symbols and search them by name.",
+            instructions=self._load_instructions(),
            tools=[
                self.get_all_symbols,
                self.get_symbols_by_name,