Enhance tool design and improve fetch_page functionality

Merge pull request #25 from pardnchiu/develop

Author: pardnchiu

configs/jsons/providors/gemini.json

@@ -30,5 +30,9 @@
   "gemini-3.1-pro-preview-customtools": {
     "description": "Tool-first variant optimized for agentic workflows and custom tool integration",
     "thinking_config": "level"
+  },
+  "gemini-3.5-flash": {
+    "description": "Top-tier Flash with cutting-edge agentic and coding performance at scale",
+    "thinking_config": "level"
   }
 }

configs/prompts/discord_format.md

@@ -13,12 +13,6 @@ Discord does **not** support HTML, LaTeX, or tables — emitting any of these re
 
 ---
 
-## Character Limit
-
-Discord per-message limit is 2000 characters (Nitro 4000). Keep every response strictly within **1600 characters** (hard limit, must not exceed) to leave headroom for prefix/footer.
-
----
-
 ## Markdown Format (Discord rendering — strictly follow)
 
 **Inline**
@@ -73,7 +67,6 @@ go, js, ts, py, rs, java, c, cpp, cs, php, rb, swift, kt, sh, bash, sql, json, y
 
 **Limits**
 
-- Message text: 2000 (Nitro 4000)
 - Attachments per message: 10
 - Attachment size: 10 MB (Nitro Basic 50 MB / Nitro 500 MB)
 

configs/prompts/discord_system_prompt.md

@@ -4,7 +4,6 @@
 
 - Markdown only — `**bold**`, `*italic*`, `` `code` ``, ```` ```lang\n…\n``` ````, `> quote`, `- bullet`, `# heading` (H1–H3 only). Full list in `discord_format`.
 - **No HTML** (`<b>`, `<div>`, etc. render as literal characters). **No LaTeX, no tables.**
-- Discord per-message limit is 2000 chars (Nitro 4000) — keep replies within **1600 chars**.
 
 **Before composing the FIRST reply / push / scheduling ack in this session, call `discord_format`** to load the complete markdown reference (special tokens, code block languages, file/voice markers, supported image formats). Cached in context for the rest of the session.
 
@@ -32,7 +31,6 @@ You are replying to user messages in a Discord channel.
 - If one sentence suffices, don't use three
 
 ### Tool Usage
-- Tool usage rules remain unchanged — **never skip a tool call due to the character limit**
 - After retrieving data with tools, include only the key points directly relevant to the user's question; omit redundant details
 
 ### Disambiguation (mandatory — never loop back-and-forth in text)
@@ -100,13 +98,8 @@ When a user message contains any of the following time-delay intents, **must** g
 - Recent messages in the current channel are **already loaded into context** — for queries like 「之前說過什麼」、「聊過什麼」、「上次提到的內容」, **answer directly from context first without calling `search_conversation_history`**
 - `search_conversation_history` is only for history beyond what is in context, or when keyword-exact matching is needed
 
-### File Output Tasks (overrides character limit rules)
+### File Output Tasks
 
 When the final output of a task is a **local file** (md, json, txt, etc.):
-- **The 1600-character limit applies only to the Discord message reply itself**, not to the file content
-- File content prioritizes completeness and is not subject to the character limit
 - The Discord message only needs to say "現在傳送中，檔案位於 `{path}`" (in-progress tense) and attach `[SEND_FILE:{path}]` if needed
-
-### When Reply Is Incomplete
-- If the content cannot be fully presented within the character limit, prioritize the most essential conclusion or answer
-- At the end, explicitly tell the user they can ask follow-up questions or that more detail is available
+- File content itself prioritizes completeness; do not duplicate the file body into the channel message

configs/prompts/telegram_format.md

@@ -15,12 +15,6 @@ If a single character of markdown (`**`, `__`, `` ` ``, leading `-` / `*` / `#`)
 
 ---
 
-## Character Limit
-
-Telegram message text limit is 4096 characters — keep every response strictly within **3500 characters** (hard limit; reserves headroom for escape expansion).
-
----
-
 ## HTML Format (Telegram rendering — strictly follow)
 
 **Allowed inline tags**

configs/prompts/telegram_system_prompt.md

@@ -5,7 +5,6 @@
 - HTML only — `<b>`, `<i>`, `<code>`, `<pre>`, `<a href>`, `<blockquote>` (full list in `telegram_format`).
 - **Forbidden markdown — any of these leaks renders as literal characters and breaks the message:** `**bold**`, `__underline__`, `` `code` ``, leading `#`, leading `-` / `*` bullets, `[text](url)`, ``` ```lang ``` ``` fences.
 - **Self-check before every send:** scan the message for `**`, `__`, `~~`, `` ` ``, `#`, `- ` / `* ` at line start, `[..](..)`. If present, rewrite using HTML tags (e.g. `**x**` → `<b>x</b>`; `` `x` `` → `<code>x</code>`; `- x` → `• x`).
-- Telegram message limit is 4096 chars — keep replies within **3500 chars**.
 
 **Before composing the FIRST reply / push / scheduling ack in this session, call `telegram_format`** to load the complete HTML reference (allowed tags, escape rules, file/voice markers, concrete rewrite table). Cached in context for the rest of the session.
 
@@ -33,7 +32,6 @@ You are replying to user messages in a Telegram chat.
 - If one sentence suffices, don't use three
 
 ### Tool Usage
-- Tool usage rules remain unchanged — **never skip a tool call due to the character limit**
 - After retrieving data with tools, include only the key points directly relevant to the user's question; omit redundant details
 
 ### Disambiguation (mandatory — never loop back-and-forth in text)
@@ -101,13 +99,8 @@ When a user message contains any of the following time-delay intents, **must** g
 - Recent messages in the current chat are **already loaded into context** — for queries like 「之前說過什麼」、「聊過什麼」、「上次提到的內容」, **answer directly from context first without calling `search_conversation_history`**
 - `search_conversation_history` is only for history beyond what is in context, or when keyword-exact matching is needed
 
-### File Output Tasks (overrides character limit rules)
+### File Output Tasks
 
 When the final output of a task is a **local file** (md, json, txt, etc.):
-- **The 3500-character limit applies only to the Telegram message reply itself**, not to the file content
-- File content prioritizes completeness and is not subject to the character limit
 - The Telegram message only needs to say "現在傳送中，檔案位於 <code>{path}</code>" (in-progress tense) and attach `[SEND_FILE:{path}]` if needed
-
-### When Reply Is Incomplete
-- If the content cannot be fully presented within the character limit, prioritize the most essential conclusion or answer
-- At the end, explicitly tell the user they can ask follow-up questions or that more detail is available
+- File content itself prioritizes completeness; do not duplicate the file body into the chat message

extensions/apis/themealdb.json

@@ -1,6 +1,6 @@
 {
   "name": "themealdb_search",
-  "description": "[system-default] Search recipes from TheMealDB by name.",
+  "description": "[system-default] Search TheMealDB recipes by meal name. Returns ingredients, instructions, image, YouTube link. Use when the user names a specific recipe.",
   "always_allow": true,
   "endpoint": {
     "url": "https://www.themealdb.com/api/json/v1/1/search.php",

extensions/skills/api-tool-add/SKILL.md

@@ -246,8 +246,8 @@ multiSelect: false
 
 ```json
 {
-  "name": "get_user",
-  "description": "Retrieve user profile by ID.",
+  "name": "fetch_user_profile",
+  "description": "Retrieve a user's full profile (name, email, role, audit timestamps) from the example.com user directory. Use when the user mentions a user ID or asks 'who is X', 'what's user 42's role', or before any operation that needs to verify a user exists. Prefer over list_users when you already know the exact user_id — list_users is paginated and slower for single-record lookups.",
   "endpoint": {
     "url": "https://api.example.com/users/{user_id}",
     "method": "GET",
@@ -267,12 +267,12 @@ multiSelect: false
   "parameters": {
     "user_id": {
       "type": "string",
-      "description": "User identifier, matches {user_id} in URL path.",
+      "description": "Numeric user identifier as a string (e.g. \"42\", \"10293\"). Matches {user_id} placeholder in the URL path. Must be the canonical ID, not username or email — use search_users first if you only have name/email.",
       "required": true
     },
     "include_deleted": {
       "type": "boolean",
-      "description": "Include soft-deleted users when true.",
+      "description": "When true, includes users with deleted_at != null (soft-deleted). Default false returns 404 for soft-deleted users. Set true only for audit / compliance use cases where deletion history matters.",
       "required": false,
       "default": false
     }
@@ -302,8 +302,8 @@ multiSelect: false
 
 | 欄位 | 必填 | 規則 |
 |---|---|---|
-| `name` | ✅ | snake_case，不加 `api_` 前綴（runtime 自動補） |
-| `description` | ✅ | 一句動詞開頭，描述用途；英文優先 |
+| `name` | ✅ | snake_case，動詞+名詞，直白具體（`fetch_user_profile` ≻ `user_get`），不加 `api_` 前綴（runtime 自動補） |
+| `description` | ✅ | 英文。**只描述使用情境**（何時呼叫／與相似 tool 的取捨），**極致精簡精準**：一兩句寫清觸發信號即停。lazy-schema 下這是 LLM 召喚 tool 的唯一依據，但冗詞稀釋訊號；禁填充語、禁實作八卦、禁呼叫合約細節（型別／enum／邊界丟 `parameters`）。純「執行什麼」一句話 trigger coverage 不足必失敗；超過兩三句通常代表夾雜了該住 schema 的內容。長度建議 60-200 chars |
 | `always_allow` | optional | `true` = `agen cli` 跳過 confirm；缺省／`false` = 每次 confirm。僅讀取／無副作用 endpoint 可設 `true`，由 Gate 6 決定 |
 | `endpoint.url` | ✅ | 完整 URL，path 變數用 `{var_name}` |
 | `endpoint.method` | ✅ | `GET`／`POST`／`PUT`／`PATCH`／`DELETE` |
@@ -315,10 +315,10 @@ multiSelect: false
 | `auth.header` | conditional | 僅 `apikey` 可用；省略時預設 `X-API-Key` |
 | `auth.env` | ✅（若有 auth） | keychain key 名（SCREAMING_SNAKE_CASE）；runtime 走 `keychain.Get`，**不**讀 shell env |
 | `parameters.<name>.type` | ✅ | `string`／`integer`／`number`／`boolean`／`array`／`object` |
-| `parameters.<name>.description` | ✅ | 用途 + 範例值 |
+| `parameters.<name>.description` | ✅ | 英文。完整呼叫合約：用途 + 型別與單位（秒／毫秒、bytes／MiB）+ 接受值（enum 含每值意涵、regex、值域）+ 至少一個範例值（非平凡型別必給）+ 與其他參數互動（`required when X=Y`）+ 邊界／失敗模式。非平凡型別（`object`／`array`／含 `enum`）短於 20 chars 視為不完整 |
 | `parameters.<name>.required` | ✅ | `true`／`false`（明確標示，勿省略） |
-| `parameters.<name>.default` | optional | 非必填參數建議給；型別需匹配 `type` |
-| `parameters.<name>.enum` | optional | 限制可選值 |
+| `parameters.<name>.default` | optional | 非必填參數**必給**；型別需匹配 `type`；缺 default LLM 不知道省略此參數的語意 |
+| `parameters.<name>.enum` | optional | 限制可選值；每個 enum value 在 description 內解釋其意涵（不只列字串） |
 | `response.format` | ✅ | 一律填 `json`（目前 adapter 僅支援 JSON 回應） |
 
 ### Path 變數與 parameters 對應
@@ -389,6 +389,8 @@ Wrote N tool(s) to ~/.config/agenvoy/tools/api/
 6. **Host 已確認**：intranet／localhost host 已通過 Gate 3 確認或替換。
 7. **試打通過**：Gate 5 對該 endpoint 取得 2xx（或使用者明確允許的 4xx／5xx）。未試打或 unreachable → **拒絕寫入**。
 8. **always_allow 確認**：Gate 6 已決定；`always_allow=true` 的 endpoint 必須為純讀取／無外部副作用（寫入類、刪除類、發送類即使使用者批量選 true 也須個別二次確認）。
+9. **Description 極致精簡精準**：只描述使用情境（何時用／與相似 tool 的取捨），一兩句寫清觸發信號即停。純「執行什麼」一句話必失敗（trigger coverage 不足）；夾雜實作細節／呼叫合約／填充語也必失敗（冗詞稀釋訊號）。長度 60-200 chars。
+10. **Parameter description 完整**：每個 `parameters.<name>.description` 含型別／單位／接受值／範例／互動關係。非平凡型別（`object`／`array`／含 `enum`）短於 20 chars 必失敗。
 
 ---
 

extensions/skills/script-tool-add/SKILL.md

@@ -65,7 +65,11 @@ Q3 question: "語言偏好？"
 
 #### 命名
 
-`<tool_name>`：snake_case，**不**加 `script_` 前綴（runtime 自動補）。動詞_名詞 或 名詞_動詞，例：`rsi_calc`、`csv_dedupe`、`reddit_top`。
+`<tool_name>`：snake_case，**不**加 `script_` 前綴（runtime 自動補）。直白具體：動詞+名詞，例：`calculate_rsi`、`deduplicate_csv`、`fetch_reddit_top`。避免動詞模糊（`process_*`／`handle_*`）或名詞前置造成 LLM 選擇困難（`rsi_calc` ≺ `calculate_rsi`，動詞前置與其他 tool 對齊）。
+
+#### 工具描述（`tool.json` 頂層 `description`）
+
+英文。**只描述使用情境**（何時呼叫／與相似 tool 的取捨），**極致精簡精準**——一兩句寫清觸發信號即停。lazy-schema 下這是 LLM 召喚 tool 的唯一依據，但冗詞稀釋訊號；禁填充語、禁實作八卦、禁呼叫合約細節（型別／enum／邊界丟 `parameters`）。長度建議 60-200 chars；超過兩三句通常代表夾雜了該住 schema 的內容。
 
 #### 參數 schema
 
@@ -82,11 +86,11 @@ Q3 question: "語言偏好？"
 | 欄位 | 必填 | 規則 |
 |---|---|---|
 | `type` | ✅ | `string`／`integer`／`number`／`boolean`／`array`／`object` |
-| `description` | ✅ | 用途 + 範例值 + 邊界（如「integer between 1 and 100」） |
-| `default` | optional | 非必填參數**強烈建議**給；型別需匹配 `type` |
-| `enum` | optional | 限制可選值 |
+| `description` | ✅ | 英文。完整呼叫合約：用途 + 型別與單位（秒／毫秒、bytes／MiB）+ 接受值（enum 含每值意涵、regex、值域）+ 至少一個範例（非平凡型別必給）+ 與其他參數互動 + 邊界。非平凡型別（`object`／`array`／含 `enum`）短於 20 chars 視為不完整 |
+| `default` | optional | 非必填參數**必給**；型別需匹配 `type`；缺 default LLM 不知道省略此參數的語意 |
+| `enum` | optional | 限制可選值；每個 enum value 在 description 內解釋其意涵 |
 
-**為何 description 要寫範例與邊界**：LLM 看 schema 決定如何呼叫，含範例的 description 命中率顯著高於純抽象描述。
+**為何 schema description 要這麼完整**：schema 按需注入（非 `AlwaysLoad` 的 tool 預設帶 stub schema）；一旦注入後 LLM 立即基於 description 決定如何填值。缺範例／單位／互動關係 → trial-and-error → 失敗訊息浪費 token。
 
 #### 詢問規則
 
@@ -352,19 +356,19 @@ multiSelect: false
 
 ```json
 {
-  "name": "rsi_calc",
-  "description": "Compute RSI (Relative Strength Index) for a given ticker over N periods.",
+  "name": "calculate_rsi",
+  "description": "Compute the Relative Strength Index (RSI) momentum oscillator for a given ticker over N trading periods. Use when the user asks 'is X overbought/oversold', 'compute RSI for Y', or mentions any momentum / mean-reversion analysis. RSI > 70 typically signals overbought, < 30 oversold — the tool returns the raw number plus a derived signal label. Pair with fetch_yahoo_finance when you need the underlying OHLCV data first.",
   "always_allow": true,
   "parameters": {
     "type": "object",
     "properties": {
       "symbol": {
         "type": "string",
-        "description": "Ticker symbol such as AAPL, SPY, BTC-USD."
+        "description": "Ticker symbol in Yahoo Finance format (e.g. \"AAPL\" for stocks, \"BTC-USD\" for crypto, \"^GSPC\" for indices). Case-insensitive but uppercase is preferred. Must be a single ticker — for batch use, call the tool repeatedly."
       },
       "period": {
         "type": "integer",
-        "description": "RSI period in trading days, integer between 2 and 200.",
+        "description": "RSI lookback window in trading days. Integer between 2 and 200 (typical: 14 for daily, 9 for short-term, 25 for swing trading). Larger periods smooth the signal but lag price action.",
         "default": 14
       }
     },
@@ -447,6 +451,8 @@ Gate 4 涉及 secret 的 tool，keychain 已於該關卡透過 `store_secret` 
 9. **Secret 不留明文**：所有 secret 透過 `/v1/key` 取得，不寫死、不收 plaintext 參數
 10. **試跑通過**：Gate 6 取得 exit 0 + 合法 JSON stdout（或使用者明確接受的非 JSON 輸出）
 11. **always_allow 確認**：Gate 7 已決定；寫入類／發送類 script 即使選 `true` 已二次確認
+12. **Description 極致精簡精準**：`tool.json.description` 只描述使用情境（何時用／與相似 tool 的取捨），一兩句寫清觸發信號即停。純「執行什麼」一句話必失敗（trigger coverage 不足）；夾雜實作細節／呼叫合約／填充語也必失敗（冗詞稀釋訊號）。長度 60-200 chars。
+13. **Parameter description 完整**：每個 `properties[*].description` 含型別／單位／接受值／範例／互動關係。非平凡型別（`object`／`array`／含 `enum`）短於 20 chars 必失敗。
 
 ---