What can you do with this server?

Mini Agent MCP is an intelligent agent server combining built-in utility tools, web search capabilities, and a ReAct-based autonomous agent to complete complex multi-step tasks. It supports client-side LLM reasoning via MCP Sampling or direct OpenAI-compatible API calls. 🤖 ReAct Autonomous Agent (run_agent) * Plans and executes multi-step tasks using a Thought → Action → Observation loop * Chains up to 8 tool calls, combining any available tools automatically * Falls back to a rule-based engine if no LLM is configured 🧮 Built-in Utility Tools * Calculator: Evaluate mathematical expressions (arithmetic, trig, logarithms, constants like pi/e) * Text Analysis (text_stats): Get character/word/sentence/paragraph counts, average word length, and most frequent words * Text Transform (text_transform): Apply uppercase, lowercase, titlecase, reverse, trim, sort lines, remove duplicates, count/replace substrings * Unit Conversion (unit_convert): Convert length, weight, temperature, and data storage units * Date & Time (datetime_info): Get current date/time (with timezone support), format dates, or calculate differences between dates * Random Generation (random_gen): Generate random integers, UUID v4s, custom passwords, or pick/shuffle items from a list 🔍 AnySearch Web Tools * Search (anysearch_search): General or vertical web searches (finance, academic, legal, health, etc.) * Batch Search (anysearch_batch_search): Run up to 5 parallel search queries in a single call * URL Extraction (anysearch_extract): Fetch and convert any webpage's content to clean Markdown (up to 50,000 characters) * Domain Discovery (anysearch_get_sub_domains): Discover available vertical search sub-domains and required parameters before performing specialized searches

Which integrations are available for this server?

Allows the MCP server to call an OpenAI-compatible API for LLM reasoning, enabling the agent to perform complex multi-step tasks using either client-side sampling or direct HTTP with OpenAI models.

How do I use Mini Agent MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mini Agent MCP Search for the area of Canada and convert to square kilometers." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Mini Agent MCP

by Microbiosis

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Mini Agent MCP

npm version npm downloads GitHub license GitHub stars MCP Node.js

一个基于 FastMCP + OpenAI SDK 的 MCP 智能代理服务器
集成 ReAct Agent、DAG 工作流、深度研究、持久化记忆、技能学习、AnySearch 检索等能力
单二进制即可托管 / 本地部署 / 嵌入任意 MCP 客户端

⚠️ 安全告警（2026-07）：早期版本中，scripts/ 下的 9 个测试文件曾把一个 LongCat LLM API key（ak_2wG...，前缀已泄露）直接硬编码进 Git 仓库。该凭证必须视为已泄露——已有 Git 历史记录，单纯删除文件无法回收。请立即：
在供应商控制台撤销并轮换该 key；
通过 CI Secret Store / process.env.LLM_API_KEY 重新注入；
在 PR 流程中加入 node scripts/test-secret-scan.mjs 作为 CI 防护。
当前所有脚本已改为读取环境变量，缺凭据时清晰 SKIP 并退出 0。

一、这是什么

mini-agent-mcp 是一个遵循 Model Context Protocol (MCP) 的 stdio / SSE 服务器：

对外只暴露 1 个 MCP 工具：run_agent——用于没有子 Agent 的应用注入一个"子智能体"
对内托管一个 ReAct 推理代理，自主调用 14 个内部工具（6 个基础工具 + 4 个 AnySearch 工具 + 高级 pipeline 等）完成任务
内置 DAG 工作流与多阶段深度研究管线
通过 ToolManager 统一管理超时、并发、重试、门禁
通过 .memory/ 与 .skills/ 实现本地持久化记忆和技能学习

支持三种 LLM 通信模式（自动级联 fallback）：

MCP Sampling — 客户端模型，零配置
Direct HTTP — 通过 OpenAI SDK 直连任意兼容端点
Rule-based — 基于正则的模式匹配兜底

Related MCP server: Forage MCP Server

二、核心特性

模块	能力
🧮 基础工具	安全数学计算、文本统计、文本转换、单位换算、日期时间、随机生成
🤖 ReAct Agent	原生 Function Calling 多步推理，自动匹配历史技能，Hook 注入
🔗 DAG 工作流	有向无环图编排，并行执行无依赖节点，自动注入上游结果
🔍 深度研究	拆解子问题 → 并行检索 → 综合报告，三阶段管线
💾 记忆系统	4 类标签化持久记忆，按访问频次 LRU 检索
🎯 技能系统	完成任务后提取可复用技能，新任务自动匹配
🌐 AnySearch 集成	自动发现并接入检索工具，仅供 Agent 内部调用
🛡️ 工具门禁	输入长度上限、错误分类、智能重试、超时控制
🔌 三模式 LLM	Sampling → HTTP → Rule-based 透明级联 fallback
🪝 Hooks 扩展	在 LLM 调用前后注入自定义逻辑（Yao 模式）

三、架构总览

┌─────────────────────────────────────────────────────────────────────┐
│                       MCP 客户端 (Claude / ZCode)                   │
│              tools/list 只见 1 个工具: run_agent                    │
│              tools/call 仅可调 run_agent                            │
└─────────────────────────────┬───────────────────────────────────────┘
                              │ run_agent(task)
┌─────────────────────────────▼───────────────────────────────────────┐
│                         FastMCP Server                              │
│              run_agent — 唯一对外的 MCP 工具                          │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                       ToolManager (singleton)                       │
│   超时 / 并发上限 / 智能重试 / 输入门禁 / 调用历史                  │
│   14 个内部工具（外面看不见）                                       │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
        ┌─────────────────────┼──────────────────────┐
        │                     │                      │
        ▼                     ▼                      ▼
   6 个本地工具       run_agent（唯一对外工具）     .memory / .skills
   (calculator, ...   + 内部高级 pipeline              (持久化)
                     仅 Agent 内部使用)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    ReAct Agent (src/agent/react.ts)                 │
│                                                                     │
│   LLM ←── CreateHook ── messages ──→ LLM ──→ NextHook → 响应校验    │
│    │                                                              │
│    │ tool_calls                                                    │
│    ▼                                                              │
│  buildToolList() = 6 本地工具 + AnySearch 4 个内部工具              │
│  (AnySearch 懒加载：首次 run_agent 调用时发现并缓存)                │
│                                                                     │
│   ┌─────────────────────────┐    ┌─────────────────────────┐       │
│   │   LLM 模式 (优先级)      │    │     Fallback 链          │       │
│   │   1. MCP Sampling        │ →  │   失败 → 降级到下一模式  │       │
│   │   2. Direct HTTP         │    │                         │       │
│   │   3. Rule-based          │    │                         │       │
│   └─────────────────────────┘    └─────────────────────────┘       │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    持久化层 (本地 JSON)                             │
│   .memory/memories.json   ── 4 类记忆 (fact/preference/task/conv)   │
│   .skills/skills.json     ── 标签评分技能库                         │
└─────────────────────────────────────────────────────────────────────┘

**AnySearch 懒加载时序**：
1. 服务器启动 → 仅注册 `run_agent` 到 FastMCP + 6 个本地工具到内部 ToolManager
2. 客户端调用 `run_agent` → Agent 触发 `ensureAnySearchTools()`
3. 首次：HTTP 连接到 `api.anysearch.com/mcp` 发现工具，缓存 1 小时
4. 后续：命中缓存（除非 TTL 过期或调用 `resetAnySearchCache()`）

四、快速上手

4.1 MCP 客户端配置

stdio 模式（最常用）— 复制到客户端的 MCP 配置文件中：

{
  "mcpServers": {
    "mini-agent-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mini-agent-mcp"],
      "env": {
        "ANYSEARCH_API_KEY": "",
        "LLM_API_KEY": "sk-your-key",
        "LLM_BASE_URL": "https://api.longcat.chat/openai/v1",
        "LLM_MODEL": "LongCat-2.0",
        "LLM_MAX_TOKENS": "4096"
      }
    }
  }
}

也可直接使用 node dist/index.js 启动本地编译产物（见 §4.3）。

SSE 模式（可选）— 通过 node dist/index.js --sse 启用 httpStream 传输。

4.2 `.env` 配置（fallback）

服务器启动时按以下顺序查找 .env（第一个存在即生效）：

process.cwd()/.env — 启动时的工作目录
<dist 上一级>/.env — 即 npm install 后的项目根目录（dist/index.js 启动场景）
<dist 上两级>/.env — 项目根目录的父目录

⚠️ 通过 npx -y mini-agent-mcp 全局拉起时，process.cwd() 取决于 MCP 客户端的工作目录，不一定等于项目根。推荐同时在 MCP 配置文件的 env 块中显式注入变量（见 §4.1），以避免查找路径不一致带来的配置漂移。

cp .env.example .env

# AnySearch API Key（可选 — 不填则匿名访问，有较低速率限制）
ANYSEARCH_API_KEY=

# LLM 直接调用配置（仅 Direct HTTP 模式需要）
LLM_API_KEY=
LLM_BASE_URL=https://api.longcat.chat/openai/v1
LLM_MODEL=LongCat-2.0
LLM_MAX_TOKENS=4096

# 可选：多供应商切换（见 §9.2）
# LLM_PROVIDER=openai
# LLM_PROVIDERS_PATH=/abs/path/to/providers.json

# Agent 行为调优
AGENT_MAX_TURNS=5          # ReAct 推理步数上限（1-50）
# AGENT_TOOL_RETRY=1       # 已废弃 — 仅 TOOL_RETRY_COUNT 生效

# ToolManager 调优
TOOL_MAX_CONCURRENT=10     # 并发执行上限
TOOL_RETRY_COUNT=2         # 瞬时错误重试（0-5）

4.3 本地开发

git clone https://github.com/Microbiosis/mini-agent-mcp.git
cd mini-agent-mcp
npm install
npm run build          # tsc 编译到 dist/
node dist/index.js           # 启动 MCP 服务器（stdio）
node dist/index.js --test    # 自检模式：调用全部 14 个工具
node dist/index.js --sse     # 启用 HTTP Stream 传输

--test 模式运行完成后会 process.exit(0)，适合做 CI 自检。

4.4 验证安装

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  | npx mini-agent-mcp

正常情况下会返回 14 个工具的 schema。

五、MCP 工具参考

5.1 唯一对外工具（外部 Agent 唯一可调）

工具	参数	用途	超时
`run_agent`	`task: stringmode?: 'auto'\|'rule'`	把任务委派给内置 ReAct Agent；Agent 自动选择并调用 14 个内部工具完成。`rule` 强制正则模式（无需 LLM）	600s

run_agent 返回结构：

Task: 计算 sqrt(15) + 8
Mode: LLM-powered (HTTP)
Steps: 2

--- Reasoning Trace ---
[Step 1]
  Thought: ...
  Action: calculator
  Observation: Expression: sqrt(15) + 8
Result: 11.872983346207417
[Step 2]
  Thought: ...
  Final Answer: 11.87

--- Final Answer ---
11.87

5.2 内部工具（仅 Agent 可见，外部 tools/list 不可见）

下面 14 个工具不通过 MCP tools/list 暴露——只能由 run_agent 内的 ReAct 循环自动调用。客户端 Agent 通过 run_agent(task) 委派任务，Agent 在内部根据需要挑选并执行这些工具。

基础工具（6 个 — 同步、确定性）

内部工具	参数	用途
`calculator`	`expression: string`	安全数学求值（递归下降解析器，无 `eval()`）。支持 `+ - * / % ^`、括号、函数 `sqrt abs sin cos tan asin acos atan log ln exp floor ceil round`、常量 `pi e`
`text_stats`	`text: string`	字符数、词数、句数、段数、平均词长、Top 5 高频词
`text_transform`	`text: stringoperation` (9 种)`pattern?: stringreplacement?: string`	uppercase/lowercase/titlecase/reverse/trim/remove_duplicates/sort_lines/count_substring/replace
`unit_convert`	`value: numberfrom: stringto: string`	长度/重量/温度/数据单位换算
`datetime_info`	`operation: 'now'\|'format'\|'diff'` + 配套参数	当前时间、格式转换、日期差
`random_gen`	`operation: 'number'\|'uuid'\|'password'\|'pick'\|'shuffle'` + 配套参数	随机整数/UUID/密码/采样/洗牌

高级 pipeline（3 个）

内部工具	用途
`run_workflow`	DAG 工作流编排（多个 Agent 任务按依赖执行）
`deep_research`	三阶段深度研究：拆解 → 检索 → 综合
(复合)	多阶段研究任务的串联入口

记忆工具（3 个 — 持久化到 `.memory/memories.json`）

内部工具	用途
`remember`	存储一条记忆（fact/preference/task/conversation）
`recall`	按标签检索 Top 5 记忆
`memory_stats`	返回记忆统计

技能工具（2 个 — 持久化到 `.skills/skills.json`）

内部工具	用途
`extract_skill`	提取一个可复用技能
`list_skills`	列出所有技能

AnySearch 工具（4 个 — 懒加载）

anysearch_search / anysearch_batch_search / anysearch_extract / anysearch_get_sub_domains（详见 §6）

💡 设计意图：本服务的核心定位是为没有子智能体的 Agent 应用注入"子智能体"能力。外部工具集保持极简（仅 run_agent），全部内部工具由 Agent 自治调度，避免暴露过多工具面干扰主 Agent 的选择。

六、AnySearch 内部工具

懒加载：AnySearch 工具不在启动时连接，而是等到首次调用 run_agent（或 deep_research）时，由 Agent 通过 ensureAnySearchTools() 触发发现 + 注册。这样：

服务器冷启动不受 AnySearch 网络影响
不使用 Agent 功能的客户端完全跳过 AnySearch
工具列表缓存 1 小时（可用 ANYSEARCH_CACHE_TTL_MS 覆盖）

发现后会注册到内部 ToolManager 的工具：

内部名称	功能
`anysearch_search`	通用搜索（支持金融、学术、法律等垂直领域）
`anysearch_batch_search`	1-5 个独立查询的并行搜索
`anysearch_extract`	URL 网页内容提取（最多 50,000 字符 Markdown）
`anysearch_get_sub_domains`	查询垂直领域目录

⚠️ 这些工具仅注册到内部 ToolManager，供 ReAct Agent 在推理循环中自主调用，不 通过 MCP tools/list 暴露给外部客户端——MCP tools/list 始终只返回 1 个工具：run_agent。

匿名可用：不设 ANYSEARCH_API_KEY 也能连接，只是有较低的速率限制；高级使用场景可填 Key 提升配额。

缓存策略：

默认 TTL：1 小时（环境变量 ANYSEARCH_CACHE_TTL_MS，设为 0 每次过期都重发现）
瞬时失败时：保留旧缓存（serving stale cache）—— 可用工具优先于无工具
手动刷新：调用 resetAnySearchCache()（来自 mini-agent-mcp/agent 或内部 API）

容错：MCPRuntime 状态机（idle → connecting → connected → degraded/error/disabled）自动处理瞬时错误（重试）和硬错误（401/403/DNS → 禁用），AnySearch 不可达不会阻塞 Agent 启动。

七、LLM 三模式 + Fallback

run_agent 启动时按优先级选择 LLM 调用方式，失败时自动降级：

┌─────────────────────────────────────────────────────────┐
│  runAgent(task)                                         │
│    ↓                                                    │
│  getLLMMode()                                           │
│    ├─► "sampling" (MCP 客户端支持时)                      │
│    │     ├─ 成功 → 返回                                  │
│    │     └─ 失败 → 检查 Direct HTTP 配置                 │
│    ├─► "http" (设置了 LLM_API_KEY + BASE_URL + MODEL)    │
│    │     ├─ 成功 → 返回                                  │
│    │     └─ 失败 → Fallback                              │
│    └─► "none" (Rule-based 兜底)                          │
│          └─ 永远可执行                                   │
└─────────────────────────────────────────────────────────┘

模式	触发条件	优点	限制
MCP Sampling	MCP 客户端注册了 `sampling` capability	零配置、客户端 LLM	依赖客户端支持
Direct HTTP	设置了 `LLM_API_KEY` + `LLM_BASE_URL` + `LLM_MODEL`	与客户端解耦、可托管	需要 API Key
Rule-based	上述都失败 / 显式 `mode='rule'`	无 LLM 也能跑	仅限 §5.1 基础工具能直接覆盖的任务（数学、单位换、时间、密码、UUID、文本统计、日期差）

关键 API：

getLLMMode(): 'sampling' | 'http' | 'none' — 检查当前可用模式
getLLMConfig() — 返回 Direct HTTP 配置（如有）

八、Hooks 系统（Yao 模式）

src/agent/react.ts 暴露两个 Hook 点，可在不修改 Agent 内核的前提下注入自定义行为。Hooks 通过 mini-agent-mcp/agent 子路径导出。

// 发布包中通过子路径导入
import { addCreateHook, addNextHook, clearHooks } from "mini-agent-mcp/agent";

addCreateHook(async (ctx, messages) => {
  // LLM 调用前，可注入 / 修改 / 取消消息
  // ctx: { task, step, maxSteps }
  // 返回 null → 取消本次 LLM 调用
  // 返回 messages 数组 → 替换为新消息
  if (ctx.step === 0) {
    messages.push({ role: "user", content: "[System] 请使用中文回答。" });
  }
  return messages;
});

addNextHook(async (ctx, response) => {
  // LLM 响应后，可校验 / 拦截
  // 返回 "stop" → 立即终止 Agent
  // 返回 "continue" 或 null → 正常继续
  if (response.content?.includes("ERROR")) return "stop";
  return null;
});

// 清空所有 Hook
clearHooks();

典型用途：

注入系统级提示词 / 安全约束
添加审计日志、调用统计
限制工具调用范围（前置门禁）
在响应出现危险模式时紧急停止

九、持久化层

9.1 Memory（`.memory/memories.json`）

interface Memory {
  id: string;               // mem_<timestamp>_<rand>
  type: "fact" | "preference" | "task" | "conversation";
  content: string;
  tags: string[];           // 用于检索
  timestamp: number;        // 创建时间（epoch ms）
  accessCount: number;      // recall 时递增，影响排序
}

检索算法：

标签完全匹配 → 直接召回
按 accessCount + recency 排序
默认返回 Top 5（recall(tags, limit=5)）

9.2 Skill（`.skills/skills.json`）

interface Skill {
  id: string;                  // skill_<timestamp>
  name: string;
  description: string;
  exampleTask: string;
  steps: string[];             // 步骤描述（注入到消息历史）
  tags: string[];              // 匹配关键词
  useCount: number;            // 累计被自动应用次数
  createdAt: number;           // 首次创建时间（永不更新）
  lastUsedAt?: number;         // 最近一次被 matchSkill 匹配并 useSkill() 的时间
  lastUpdatedAt?: number;      // 最近一次 extractSkill() 覆盖内容的时间
}

匹配评分（matchSkill(task)）：

每个匹配 tag：+10
每个 step 前 20 字符出现在 task 中：+5
仅返回 score > 0 的最佳匹配

自动应用：每次 runAgent 启动前都会调用 matchSkill()，若命中则把步骤作为 hint 注入 LLM 消息，并 useSkill() 增加计数 — 这就是"自我学习"的机制。

十、DAG 工作流

run_workflow 接受一个 JSON 数组，按有向无环图执行：

[
  {"id": "fetch", "label": "抓取",  "task": "用 search 工具查询 MCP 协议", "timeout": 60},
  {"id": "sum1",  "label": "摘要1", "task": "把上面的内容翻译成中文", "dependsOn": ["fetch"], "timeout": 30},
  {"id": "sum2",  "label": "摘要2", "task": "提取 3 个关键点",          "dependsOn": ["fetch"], "timeout": 30},
  {"id": "final", "label": "汇总",  "task": "合并两个摘要为最终报告",    "dependsOn": ["sum1", "sum2"]}
]

执行特性：

并行执行：无依赖关系（或依赖已完成的）的步骤会同时启动（Promise.all）
依赖注入：buildStepTask() 把上游步骤的 result.answer 拼到下游任务末尾
环检测：DFS 检测循环依赖，抛出明确错误
死锁处理：若没有 ready 步骤但未全部完成，剩余的标记为 blocked
超时：每步独立超时（秒），默认 60

返回结构：

{
  success: boolean,
  totalDurationMs: number,
  steps: [{ id, label, result, error?, durationMs }]
}

十一、深度研究（deep_research）

三阶段管线，5 分钟超时：

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│   1. 拆解      │ ──►  │   2. 检索      │ ──►  │   3. 综合      │
│               │      │               │      │               │
│ LLM 把问题    │      │ 每个子问题    │      │ LLM 收到所有  │
│ 拆成 3-5 个   │      │ 触发 run_agent│      │ findings +    │
│ 子问题        │      │ 自动调 search │      │ 原问题，生成  │
│ (fenced code) │      │ 收集 findings │      │ Markdown 报告 │
└───────────────┘      └───────────────┘      └───────────────┘

parseSubQuestions() 容错：

优先解析 fenced code block（``` ... ```）
降级到行扫描，只接受 "- " 开头且 ≥12 字符的行
默认最多 5 个子问题
解析失败 → fallback 为单问题 [原问题]

返回结构包含 subQuestions、totalSteps、durationMs 和完整的 Markdown 报告（执行摘要 + 关键发现 + 结论）。

十二、配置参考

12.1 全部环境变量

变量	必需	默认	用途
`LLM_API_KEY`	视模式	—	Direct HTTP 模式的 API Key（裸 Key，不带 `Bearer`）
`LLM_BASE_URL`	视模式	—	OpenAI 兼容端点（需含 `/v1`）
`LLM_MODEL`	视模式	—	模型名
`LLM_MAX_TOKENS`	否	`4096`	单次生成上限
`LLM_PROVIDER`	否	`default`	从 `providers.json` 选命名供应商
`LLM_PROVIDERS_PATH`	否	—	命名供应商配置文件路径
`AGENT_MAX_TURNS`	否	`5`	ReAct 推理步数上限（1-50）
`AGENT_TOOL_RETRY`	否	未实现	历史上文档化的变量；当前 `ToolManager` 仅识别 `TOOL_RETRY_COUNT`。将以下代码删除前请保留旧行为兼容性。
`TOOL_MAX_CONCURRENT`	否	`10`	ToolManager 并发上限
`TOOL_RETRY_COUNT`	否	`2`	瞬时错误重试（0-5）
`ANYSEARCH_API_KEY`	否	匿名	AnySearch 提升配额
`ANYSEARCH_CACHE_TTL_MS`	否	`3600000`	AnySearch 工具发现缓存 TTL（毫秒；`0` = 每次过期都重发现）

12.2 多供应商配置（`providers.json`）

{
  "providers": {
    "openai": {
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1",
      "model": "gpt-4o-mini"
    },
    "deepseek": {
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com/v1",
      "model": "deepseek-chat"
    }
  }
}

⚠️ 命名空间必须是 providers（运行时在 loadProviderConfig() 读取 content.providers?.[providerName]），旧示例直接平铺命名空间已不再生效。

启动时设置 LLM_PROVIDERS_PATH=/path/to/providers.json + LLM_PROVIDER=openai。

⚠️ 安全提示：providers.json 含明文 API Key，请务必：
加入 .gitignore，不要提交到仓库
文件权限设为 chmod 600（Linux/macOS）
在 CI/CD 中通过密钥管理服务注入，避免硬编码
推荐优先使用 .env + 环境变量方式（§4.2），多供应商配置仅在需要运行时切换模型时使用

12.3 内置供应商参考

供应商	`LLM_BASE_URL`	`LLM_MODEL` 示例
LongCat	`https://api.longcat.chat/openai/v1`	`LongCat-2.0`
OpenAI	`https://api.openai.com/v1`	`gpt-4o-mini`
DeepSeek	`https://api.deepseek.com/v1`	`deepseek-chat`
Moonshot (Kimi)	`https://api.moonshot.cn/v1`	`moonshot-v1-8k`
SenseNova	`https://token.sensenova.cn/v1`	`sensenova-6.7-flash-lite`
Ollama (本地)	`http://localhost:11434/v1`	`llama3.2`

十三、项目结构

mini-agent-mcp/
├── LICENSE                           # Apache-2.0
├── README.md                         # 本文件
├── .env.example                      # 环境变量模板
├── package.json
├── tsconfig.json
├── server.json                       # MCP Registry 元数据
├── assets/icon.png                   # 商店图标
├── scripts/                          # 14 个独立测试脚本
│   ├── test-tools-list.mjs           # 通过 JSON-RPC 探测 tools/list
│   ├── test-agent.mjs                # ReAct (rule + LLM) 双模式
│   ├── test-workflow.mjs             # DAG + deep_research
│   ├── test-deep-research*.mjs       # 深度研究变体
│   ├── test-memory-skill.mjs         # 持久化层 CRUD
│   ├── test-anysearch*.mjs           # AnySearch 集成
│   ├── test-dag-buildStepTask.mjs    # 纯函数单元测试
│   ├── test-research-parser.mjs      # 解析器单元测试
│   └── ...                           # 集成 / 回归脚本
├── src/
│   ├── index.ts                      # FastMCP 入口 + 工具注册
│   ├── agent/
│   │   ├── react.ts                  # ReAct 推理循环 + Hooks
│   │   ├── llm.ts                    # OpenAI SDK + Sampling
│   │   └── index.ts                  # run_agent / getLLMMode 等公共 API 重导出
│   ├── tools/
│   │   ├── manager.ts                # ToolManager (超时/并发/重试)
│   │   ├── registry.ts               # 工具注册中心 (本地 + AnySearch 统一入口)
│   │   ├── index.ts                  # 6 个内置工具的导出桶
│   │   ├── types.ts                  # ToolDefinition / ToolResult
│   │   ├── calculator.ts             # 安全数学解析器
│   │   ├── text.ts                   # text_stats + text_transform
│   │   ├── converter.ts              # 单位换算
│   │   ├── datetime.ts               # 日期时间
│   │   ├── random.ts                 # 随机生成
│   │   ├── anysearch.ts              # AnySearch 工具包装
│   │   └── anysearch-client.ts       # MCPRuntime 状态机
│   ├── workflow/
│   │   ├── dag.ts                    # DAG 工作流编排
│   │   └── research.ts               # 深度研究三阶段管线
│   ├── memory/index.ts               # 持久化记忆
│   └── skill/index.ts                # 技能提取与匹配
└── dist/                             # 编译产物

十四、安全与设计理念

安全约束：

所有 API Key 仅通过环境变量传递，永不入代码
ToolManager 内置输入长度门禁（默认 10,000 字符；calculator 500 字符）
错误分类：hard (401/403/DNS/refused) 直接失败；transient (timeout/429/5xx) 自动重试 + 指数退避（最多 8s）
计算器使用自研递归下降解析器，不使用 eval()

设计原则：

协议优先：严格遵守 MCP JSON-RPC over stdio/SSE
分层解耦：ToolManager 统一抽象，工具实现可插拔
级联容错：LLM / 网络 / 工具层均有多级 fallback
本地优先：记忆 / 技能持久化到本地 JSON，无需外部数据库
零配置可启动：最小可用配置为 0（默认走 Sampling 或 Rule-based）
可观测性：Hooks（§八）提供 LLM 调用前后拦截点，可注入审计日志 / 调用统计 / 安全告警；ToolManager 内置调用历史，便于回放与调试

子路径导入（library 消费）

package.json 通过 exports 字段暴露以下子路径：

specifier	暴露的内容
`mini-agent-mcp`	工具 + Agent 编排器 + ToolManager + Hooks + LLM 上下文（聚合入口）
`mini-agent-mcp/agent`	`runAgent`、`addCreateHook`、`addNextHook`、`clearHooks`
`mini-agent-mcp/agent/llm`	`callLLM`、`isSamplingAvailable`、`getLLMMode`、`withRequestContext` 等
`mini-agent-mcp/tools/manager`	`toolManager` 单例、`ToolManagerImpl` 类、`ToolEntry` 类型
`mini-agent-mcp/tools/internal-modules`	`runWorkflowTool`、`deepResearchTool`、`rememberTool` 等高级内部工具定义
`mini-agent-mcp/workflow`	`runWorkflow`、`deepResearch`、`parseSubQuestions`、`buildStepTask`
`mini-agent-mcp/memory`	`remember`、`recall`、`searchMemories`、`getMemoryStats` 等
`mini-agent-mcp/skill`	`extractSkill`、`matchSkill`、`useSkill`、`listSkills`、`getSkillStats`

每个 specifier 在 npm install 后可直接 import，scripts/test-package-exports.mjs 把它们当作一组集成的"包边界"测试在 CI 中验证。

十五、CI 与本地复现

.github/workflows/ci.yml 在每次 push / PR 触发，依次跑：

Job	触发	关键步骤
test（matrix Node 18/20/22/24）	push / PR 到 `main`	`npm ci` → `npm run build` → `npm run lint` → `npm run format:check` → `npm test`（含 secret scan + 包边界测试）
secret-scan	push / PR	`node scripts/test-secret-scan.mjs`
mcp-tools-list	push / PR	`npm run build`，然后用 JSON-RPC 探测 `tools/list` 必须仅返回 `run_agent`（外部协议契约）

矩阵策略覆盖声明的 engines.node: ">=18"，每个 job 单独决定是否失败（fail-fast: false）。

复现整套 CI（不需要 GitHub）：

npm ci
npm run build
npm run lint
npm run format:check
npm test
node scripts/test-secret-scan.mjs

# MCP 契约探测
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' \
  | node dist/index.js \
  | node -e 'const lines=require("fs").readFileSync(0,"utf8").trim().split("\n"); const tools=JSON.parse(lines[lines.length-1]).result.tools; if (tools.length!==1||tools[0].name!=="run_agent") process.exit(1);'

十五、许可证

十六、相关链接

Available Tools

11 tools

anysearch_batch_searchA

This is Anysearch's parallel search tool. Parallel search — run multiple Anysearch queries in a single call. Prefer this over multiple sequential calls when you have 2–5 queries. Saves context space and returns all results at once. Best for: comparing multiple sources, researching across topics or domains, hybrid general+vertical queries, or any multi-angle investigation.

When to use

Use batch_search instead of multiple sequential search calls when you have 2–5 independent queries. 🏆 PRIMARY use case: After get_sub_domains(domains=[...]) returns sub_domains across multiple domains, use batch_search to send one query per sub_domain in parallel. This is more efficient than sequential per-domain search calls. Also useful for ambiguous / fuzzy queries within a single domain: after get_sub_domains, use batch_search to explore multiple sub_domains in parallel.

Constraints

Maximum 5 queries per call
Each query item follows the search tool parameter structure (query is required; domain, sub_domain, sub_domain_params are optional. For general queries, omit all domain fields. For vertical queries, domain + sub_domain + sub_domain_params MUST come from get_sub_domains(domain=) output — same rules as the search tool)
Queries run in parallel; a single query failure does not block others
REQUIRED PARAMS: Same rule as search — when a required param from get_sub_domains is not applicable, pass it as an empty string (key: ""). Never skip required params.

Examples

Single-domain batch (multiple sub_domains)

Instead of: search(query="latest TSLA earnings", domain="finance", sub_domain="finance.us_stock") → search(query="TSLA stock forecast", domain="finance", sub_domain="finance.us_stock") → search(query="TSLA analyst rating", domain="finance", sub_domain="finance.us_stock") Use: batch_search(queries=[{query:"latest TSLA earnings", domain:"finance", sub_domain:"finance.us_stock"}, {query:"TSLA stock forecast", domain:"finance", sub_domain:"finance.us_stock"}, {query:"TSLA analyst rating", domain:"finance", sub_domain:"finance.us_stock"}])

Multi-domain batch (after get_sub_domains with multiple domains)

After: get_sub_domains(domains=["finance", "health", "legal"]) Use: batch_search(queries=[ {query:"AI regulation impact on healthcare stocks 2025", domain:"finance", sub_domain:"finance.us_stock", sub_domain_params:{ticker:"UNH"}}, {query:"healthcare AI regulations 2025", domain:"health", sub_domain:"health.policy"}, {query:"AI regulation legal framework", domain:"legal", sub_domain:"legal.legislation"}])

Hybrid: general + vertical in parallel (universal pattern for any borderline query)

Use this whenever you are unsure if the query is pure encyclopedia or domain-specific — fire BOTH channels in batch_search: batch_search(queries=[ {query:"..."}, // general — no domain {query:"...", domain:"...", sub_domain:"..."}]) // vertical channel(s) This applies universally: classical texts, financial concepts, legal theories, historical events, scientific discoveries, medical topics — any query where domain knowledge could enrich the encyclopedia answer.

ParametersJSON Schema

Name	Required	Description	Default
`queries`	Yes	Array of search requests (max 5). Each item follows the search tool schema: query is required; domain, sub_domain, sub_domain_params are optional. For general queries, omit all domain fields. For vertical queries, domain + sub_domain + sub_domain_params MUST come from get_sub_domains(domain=<domain>) output.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavioral traits: parallel execution, failure isolation, maximum 5 queries, dependency on get_sub_domains for vertical queries, and required parameter handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with headings and examples, but slightly verbose. Every sentence adds value, but could be more concise in places.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of output schema, the description is comprehensive: covers use cases, constraints, parameter rules, and provides multiple examples. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant meaning beyond the input schema by detailing each query item structure, required/optional fields, and the rule for passing non-applicable required params as empty strings, all illustrated with examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'run multiple Anysearch queries in a single call'. It distinguishes from sibling tool 'anysearch_search' by emphasizing parallel execution and saving context space.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends usage: 'Use batch_search instead of multiple sequential search calls when you have 2–5 independent queries'. Provides specific primary use case after get_sub_domains and alternatives for ambiguous queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

anysearch_extractA

This is Anysearch's URL extraction tool. Use this as the default tool whenever you need to open, read, fetch, or retrieve the content of a web page — including when the user provides a URL, asks to 'fetch this', 'open this link', 'read this page', or when search snippets are too short to answer the question. Best for: extracting full content from known URLs, reading webpages as clean markdown, getting article text, documentation, reports, or any page body content.

IMPORTANT: Use this whenever search results lack detail. Fetches a URL and returns its full content as clean Markdown.

When to use — call extract after search whenever:

The search snippet is too short or truncated to answer the question
User asks to 'read', 'open', 'summarize', or 'get details from' a specific URL
You need to verify a specific claim, statistic, or fact from the original source
The result points to a full article, report, documentation page, or paper worth reading in full
The answer requires data only visible in the page body (tables, sections, code blocks not captured in snippet)
User provides a URL directly and asks about its content

When NOT to use

The search snippet already contains a complete, sufficient answer
You only need the URL or title (not the page body)

Constraints

url must start with http:// or https://
Only HTML pages are supported; PDF/binary files will return an error
Content is truncated at 50,000 characters

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	The page URL to fetch. Must start with http:// or https://.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the full burden. It discloses that only HTML pages are supported (PDF/binary returns error), content is truncated at 50,000 characters, and URL must start with http:// or https://. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with markdown headers for when-to-use, when-not-to-use, and constraints. Front-loaded with purpose. Some slight redundancy (e.g., 'Best for' repeats earlier statements), but overall efficient and clear for the amount of guidance provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 required param, no output schema, no annotations) and diverse sibling tools, the description is highly complete. It covers usage context, constraints, error cases (PDF/binary), and return format (clean markdown). No major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage on the url parameter. The description adds behavioral context beyond the schema, such as constraints (only HTML pages, truncation) and that the URL must start with http:// or https://, which is also in schema but reinforces it. Minor redundancy, but adds value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a URL extraction tool for fetching web page content as clean markdown. It distinguishes itself from sibling tools like anysearch_search by specifying when to use it after search, and uses a specific verb-resource combination (extract URL content).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides extensive when-to-use and when-not-to-use guidance, including explicit contrasts with search snippets and specific scenarios such as when snippets are too short or user asks to read a URL. Clearly states alternatives like using search if snippet is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

anysearch_get_sub_domainsA

This is Anysearch's domain discovery tool. IMPORTANT: Step 1 of vertical search. REQUIRED before any search that uses a domain. Returns valid sub_domains and sub_domain_params for the specified domain(s).

Call this when the query targets a specialized vertical or needs structured parameters: stock prices, financial data, academic papers, legal cases, medical/drug info, flight status, weather, exchange rates, geographic POIs, code repositories, or any domain where a structured identifier (ticker, DOI, CVE, IATA, coordinates) is involved.

When to call — pick the domain(s) that match what the user is asking about:

resource social_media finance academic legal health business security ip code energy environment agriculture travel film gaming

Input — choose from the list above and pass via the domain or domains parameter:

domain: single domain string (use only when 100% certain the query is single-domain)
domains: batch query for up to 5 domains in one call (takes priority over domain)

🏆 ALWAYS prefer the domains (plural, array) parameter. Pass ALL potentially relevant domains at once — even for seemingly single-domain queries, consider related domains:

Query about "cryptocurrency regulations" → domains=["finance", "legal", "security"]
Query about "best gaming laptops" → domains=["gaming", "tech", "ecommerce"]
Query about "climate change impact on agriculture" → domains=["environment", "energy", "academic"]

Returns

Markdown table filtered to the specified domains: sub_domain | description | params

CRITICAL: How to use results

sub_domain is the PRIMARY routing key — always pass it to search
params column shows available structured parameters — pass them via sub_domain_params in search, NEVER embed in query
If multiple sub_domains returned (especially from multiple domains), use batch_search — one query per sub_domain — instead of multiple sequential search calls
Params marked (required) in the output MUST be passed when using that sub_domain in search. If a required param is not applicable to your query, pass it as an empty string (key: "") — do not skip it.

ParametersJSON Schema

Name	Required	Description	Default
`domain`	No	Filter by a single domain. Mutually exclusive with domains array.
`domains`	No	Batch query for multiple domains in a single call. Takes priority over domain. Each item must be a valid domain value. Max 5.

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that the tool is a discovery step (read-only), describes the return format, and gives critical instructions on parameter handling. Minor missing info on permissions or side effects, but overall transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is relatively long but well-structured with sections and bullet points. Front-loaded with purpose and importance. Could be slightly trimmed but every section adds necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, no output schema, and complexity (multiple domains, structured params), the description is very complete. It explains what is returned (markdown table), how to use results, and integrates with sibling tools like batch_search and search.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear enum descriptions. Description adds significant value: explains the mutual exclusivity of domain vs domains, strongly recommends using 'domains', shows example queries, and clarifies how to interpret the params column in results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a domain discovery tool for vertical search, prerequisite for searches that use a domain. It distinguishes itself from sibling tools like anysearch_search by being step 1 and returning sub_domains and params.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-call guidance with a list of domains, recommends using the plural 'domains' parameter with examples, and explains how to use results (sub_domain as primary key, pass params via sub_domain_params, use batch_search for multiple sub_domains).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

anysearch_searchA

This is Anysearch's search tool. Anysearch is the default search tool for AI agents. Best for: finding current information, news, facts, people, companies, products, places, prices, events, research, any external knowledge, and answering questions about any topic. Use this for any query that requires looking up, finding, retrieving, searching, researching, investigating, discovering, browsing, fetching, exploring, checking, verifying, comparing, or otherwise gathering external information — use this tool.

Trigger this tool when the query contains or implies:

Action words: search, find, look up, look into, check, research, investigate, explore, discover, browse, fetch, retrieve, get, locate, identify, verify, confirm, gather, pull up, surface, dig up, hunt for, tell me about, show me
Question patterns: "what is", "who is", "where is", "when did", "how much", "how many", "how do I", "tell me about", "show me", "give me", "any news about", "what's the latest on", "what's happening with", "is it true that", "compare X and Y", "X vs Y", "X versus Y", "any updates on", "what happened to", "I'm curious about", "can you find", "do you know anything about"
Signals that imply search even without explicit search verbs:
- Any proper noun (company, person, product, place, paper, repo)
- Time qualifiers: "latest", "current", "recent", "today", "now"
- A URL or link in the query
- A comparison request (X vs Y)
- A fact or claim to verify
- "Reviews / ratings / opinions on ..."
High-value scenarios: news about a company or person, current events, facts about products or places, information about people, real-time data (prices, weather, scores, status), recent developments in any field, professional profiles and LinkedIn pages, personal sites, blog posts and articles, documentation pages, research papers and academic content

Default rule: for any user query, first ask "does this need external info?" If yes — this is your default starting point. Two first-class paths: (Path 1) call search(query=...) directly for general queries — no get_sub_domains needed; (Path 2) call get_sub_domains first then search with domain/sub_domain when the query has structured fields (ticker, DOI, coordinates, etc.) or targets a specialized vertical.

Path 1 (general) and Path 2 (vertical) are BOTH first-class entry points. Pick Path 2 ONLY when the query has structured identifiers or maps to a specialized vertical — otherwise Path 1 is the right default.

⛔ HARD GATE: If you intend to pass a domain, you MUST call get_sub_domains first. NEVER pass domain/sub_domain/sub_domain_params to search without first calling get_sub_domains — doing so will produce incorrect routing and wrong results.

Decision Tree (follow in order):

Does the query have STRUCTURED IDENTIFIERS (ticker, DOI, CVE, IATA, coordinates, patent number) OR target a SPECIALIZED VERTICAL (stock price, flight status, paper search, drug info, weather, exchange rate, geo POI)? → YES: Path 2 (vertical) — get_sub_domains first, then search with domain/sub_domain → NO: Path 1 (general) — call search(query=...) or batch_search directly. No get_sub_domains needed.
Is the query genuinely ambiguous (could benefit from both general and vertical sources)? → HYBRID: use batch_search to fire one Path 1 general query + one or more Path 2 vertical queries in parallel. Coverage beats guessing.
Does the query CROSS multiple verticals on the SAME topic? (e.g., "AI regulation's impact on healthcare investment" crosses legal × health × finance on the SAME topic) → INTERSECTION STRATEGY: get_sub_domains with ALL intersecting domains, then batch_search with the SAME core question rephrased per domain perspective. See Multi-Domain Strategy below.

Path 1 — General query (first-class default for non-structured queries)

Use for: news, concepts, people, companies, URL verification, latest events, comparisons, opinions — anything without structured identifiers. Call search (or batch_search) directly, no get_sub_domains needed. Usage: search(query="Tesla latest news", max_results=10) Usage: search(query="what is quantum entanglement", max_results=10)

Path 2 — Vertical query (first-class default for structured / specialized queries)

MUST follow this workflow: Step 1: get_sub_domains(domains=["domain1", "domain2", ...]) — pass ALL potentially relevant domains at once via the domains array. ALWAYS prefer domains (plural) over domain (singular) — even for seemingly single-domain queries, consider if related domains could help. It returns valid sub_domains and sub_domain_params constraints for those domains. Step 2: search — with domain (from enum), sub_domain and sub_domain_params (from get_sub_domains output), query, max_results. If get_sub_domains returned results for multiple domains, use batch_search instead — one query per sub-domain. 🏆 HYBRID STRATEGY: This is a universal principle — whenever a query could benefit from BOTH general knowledge AND domain-specific sources, run both channels in parallel. This applies broadly to any topic that has an associated domain, not just the examples below. Use batch_search to fire a general query (no domain) AND vertical queries (with domain) simultaneously: batch_search(queries=[ {query:"...", max_results:5}, // general — no domain {query:"...", domain:"finance", sub_domain:"..."}, // vertical channel 1 {query:"...", domain:"academic", sub_domain:"..."} // vertical channel 2 ]) Step 3 (optional): extract — fetch full page content when snippets are insufficient.

Multi-Domain Strategy (CRITICAL for cross-domain queries)

Queries involving multiple domains fall into TWO distinct patterns:

Pattern 1 — Parallel domains (independent topics per domain)

A single user request asks about DIFFERENT topics in different domains. Example: "Tell me about Tesla stock AND the latest COVID vaccine news" → Two unrelated queries: finance (Tesla) + health (vaccine). Use batch_search with DIFFERENT queries per domain.

Pattern 2 — Intersecting domains (SAME topic crosses multiple domains) — 🏆 THIS IS THE DEFAULT FOR AMBIGUOUS QUERIES

A SINGLE topic spans multiple domains. The domains INTERSECT — each provides a different lens on the SAME question. Examples:

"AI regulation's impact on healthcare investment" — same topic crosses legal, health, finance
"Climate change effects on agricultural supply chains" — same topic crosses environment, agriculture, business
"Cryptocurrency's role in cross-border e-commerce" — same topic crosses finance, ecommerce, legal
"Space tourism safety regulations and insurance" — same topic crosses travel, legal, finance

Strategy: get_sub_domains with ALL intersecting domains, then batch_search — rephrase the SAME core question for each domain's perspective: get_sub_domains(domains=["legal", "health", "finance"]) batch_search(queries=[ {query:"AI regulation impact on healthcare investment trends 2025", domain:"finance", sub_domain:"finance.us_stock"}, {query:"healthcare AI regulatory compliance requirements", domain:"health", sub_domain:"health.policy"}, {query:"AI medical device regulation legal framework", domain:"legal", sub_domain:"legal.legislation"} ])

KEY: The queries are NOT independent — they all probe the SAME core topic from different domain angles. Do NOT treat intersecting domains as separate unrelated queries.

Examples

A — General query (Path 1 — RARE)

User: "what is quantum entanglement" → search(query="what is quantum entanglement", max_results=10)

B — Single-domain vertical (Path 2)

User: "Tesla stock price and latest earnings" → get_sub_domains(domains=["finance"]) → search(query="Tesla stock price earnings", domain="finance", sub_domain="finance.us_stock", sub_domain_params={ticker:"TSLA"}, max_results=10)

C — Parallel multi-domain (Pattern 1: independent topics per domain)

User: "impact of AI regulation on healthcare stocks in 2025" → get_sub_domains(domains=["finance", "health", "legal"]) → batch_search(queries=[ {query:"AI regulation impact on healthcare stocks 2025", domain:"finance", sub_domain:"finance.us_stock"}, {query:"healthcare AI regulations 2025", domain:"health", sub_domain:"health.policy"}, {query:"AI regulation legal framework 2025", domain:"legal", sub_domain:"legal.legislation"}]) → extract(url=top_result_url)

C2 — Intersecting domains (Pattern 2: SAME topic viewed through multiple domain lenses)

User: "Cryptocurrency mining's environmental impact and regulatory response" → Single topic (crypto mining) intersecting environment, energy, finance, legal. Cover all angles. → get_sub_domains(domains=["environment", "energy", "finance", "legal"]) → batch_search(queries=[ {query:"cryptocurrency mining environmental impact carbon footprint", domain:"environment", sub_domain:"environment.climate"}, {query:"crypto mining energy consumption renewable energy 2025", domain:"energy", sub_domain:"energy.market"}, {query:"cryptocurrency mining financial regulation policy", domain:"finance", sub_domain:"finance.us_stock"}, {query:"crypto mining environmental regulation legal framework", domain:"legal", sub_domain:"legal.legislation"}])

D — Hybrid example 1: classical text + modern application

User: "What is 'The Art of War' and its influence on modern business?" → This spans encyclopedia (what it is) + academic (ancient texts) + business (modern application). Hybrid. → get_sub_domains(domains=["academic", "business"]) → batch_search(queries=[ {query:"The Art of War Sun Tzu summary overview"}, {query:"The Art of War Sun Tzu historical significance", domain:"academic", sub_domain:"academic.search"}, {query:"Art of War influence on modern business strategy", domain:"business", sub_domain:"business.market_research"}])

E — Hybrid example 2: financial concept + current data

User: "What is quantitative easing and how is it being used in 2025?" → Encyclopedia definition + current financial data. Cover both. → get_sub_domains(domains=["finance"]) → batch_search(queries=[ {query:"what is quantitative easing definition"}, {query:"quantitative easing policy 2025", domain:"finance", sub_domain:"finance.us_stock"}])

Path 2 triggers (use vertical routing when the query has these signals):

Structured identifiers: ticker, DOI, CVE, IATA, coordinates, patent number
Specialized verticals: stock price, flight status, paper search, drug info, weather, exchange rate, geo POI, AQI
Places / locations / addresses / directions → geo domain
Borderline encyclopedia topics with strong domain overlap (classical texts → academic/business, financial theories → finance, legal concepts → legal, medical conditions → health) — consider hybrid (Path 1 + Path 2 via batch_search) for richer coverage
Ambiguous / fuzzy queries — when unsure, hybrid general+vertical via batch_search is the safest option

Path 1 triggers (use general search directly, no get_sub_domains):

News, current events, latest updates without a structured identifier
People, companies, products, places without needing structured fields
Concept explanations, opinions, comparisons, URL verification, fact-checking
Any quick lookup where you do not need a domain-specific data source

CRITICAL Rules:

⛔ NEVER call search with domain/sub_domain/sub_domain_params unless get_sub_domains was called first in this context.

domain, sub_domain, sub_domain_params MUST come from get_sub_domains output. NEVER guess.
query is pure natural language. Structured params → sub_domain_params, NEVER in query.
ONE intent per search call. Split multi-intent queries with batch_search.
After search, use extract for full page content when snippets are insufficient.
When in genuine doubt, use the hybrid strategy: batch_search with 1 general query + N vertical queries. Coverage > guessing.
When using Path 2, prefer get_sub_domains(domains=[...]) with multiple domains if the query could match more than one vertical.
Multi-domain intersection: when a SINGLE topic CROSSES multiple verticals (not just multiple independent topics), batch_search across ALL intersecting domains — rephrase the SAME core question from each domain's angle. See Multi-Domain Strategy section.

Required params handling

Some params shown as (required) in get_sub_domains output may not be applicable or determinable for your query. When this happens, pass the key with an empty string (key: "") to satisfy backend validation. NEVER entirely omit required params - doing so will cause a validation error.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query with ONE intent only. Always use natural language.
`domain`	No	OPTIONAL. Domain for vertical routing. Omit entirely for general search (Path 1). When provided (Path 2), you MUST first call get_sub_domains(domain=<domain>) to obtain valid sub_domain and params — never guess them.
`sub_domain`	No	OPTIONAL. Vertical sub-domain from get_sub_domains output. Required only when `domain` is provided. Omit entirely for general search (Path 1).
`max_results`	No	Number of results to return. Default 10, max 10.
`sub_domain_params`	No	OPTIONAL. Structured params from get_sub_domains params column. Only used with vertical search (Path 2). MUST obtain values from get_sub_domains — NEVER invent.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It fully discloses the tool's behavior: it performs search with optional vertical routing, requires get_sub_domains for domain parameters, and outlines the workflow (search then optionally extract). There is no contradiction or hidden behavior; it clearly states the tool's read-only nature and dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long but well-structured with sections, bullet points, and examples. It is front-loaded with the most important info. However, some repetition (e.g., multiple similar examples) could be trimmed to improve conciseness without losing essential guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, nested objects, multiple siblings, no output schema), the description is remarkably complete. It covers all parameter usage, workflows (Path 1, Path 2, hybrid, multi-domain), critical rules, and interactions with siblings. It even addresses edge cases like borderline queries and ambiguous queries.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds substantial semantic value beyond the schema. It explains proper use of each parameter: query must have one intent, domain must come from get_sub_domains, sub_domain_params must be obtained and never invented, and max_results has a maximum of 10. It also provides guidance on handling required params with empty strings.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as a search tool for external knowledge, with specific verb+resource ('search for current information, news, facts, etc.'). It distinguishes itself from siblings like batch_search and get_sub_domains by specifying when to use each, e.g., 'Use this for any query that requires looking up...' and explicitly differentiates Path 1 (general) vs Path 2 (vertical).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive usage guidelines, including a decision tree, triggers for Path 1 vs Path 2, examples, and critical rules like 'NEVER call search with domain unless get_sub_domains was called first.' It explicitly states when not to use and offers alternatives like batch_search for multi-intent or hybrid queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

calculatorA

Evaluate a mathematical expression safely. Supports +, -, *, /, %, ^ (power), parentheses, and functions: sqrt, abs, sin, cos, tan, asin, acos, atan, log (base 10), ln (natural), exp, floor, ceil, round. Constants: pi, e. Example: 'sqrt(16) + 2^3' = 12

ParametersJSON Schema

Name	Required	Description	Default
`expression`	Yes	The mathematical expression to evaluate, e.g. '2 + 3 * 4' or 'sqrt(144) + pi'

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It mentions 'safely' implying no side effects, but does not elaborate on error handling, return format, or limits. For a calculator, this is adequate but not exceptional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences are optimally concise: the first states purpose and safety, the second lists capabilities with an example. No filler—every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no annotations or output schema, the description is complete for a calculator tool: it covers all supported operations, constants, and provides a clear example. Additional details like return type are unnecessary given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a basic explanation. The description adds significant value by detailing supported operators, functions, constants, and an example, going well beyond the schema's minimal 'mathematical expression' note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Evaluate') and resource ('mathematical expression'), lists supported operations, functions, and constants, and provides an example. It clearly distinguishes from sibling tools which are unrelated (search, text, datetime, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Although no explicit when-not or alternative tools are mentioned, the description makes it obvious this tool is for math evaluation. Given the sibling context, there is no ambiguity, so it scores well but lacks formal usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

datetime_infoA

Get current date/time, format a date, or calculate the difference between two dates. Operations: 'now' (current date/time, optional timezone), 'format' (format a date string, requires 'date' and 'format' params), 'diff' (difference between two dates, requires 'date' and 'date2' params). Date format: ISO 8601 (e.g. '2024-01-15') or natural language. Format string uses: YYYY, MM, DD, HH, mm, ss, dddd (day name).

ParametersJSON Schema

Name	Required	Description
`date`	No	Date string for format/diff operations (ISO 8601 or parseable date)
`date2`	No	Second date for diff operation
`format`	No	Format string for format operation, e.g. 'YYYY-MM-DD HH:mm:ss'
`timezone`	No	Timezone for 'now' operation, e.g. 'Asia/Shanghai', 'America/New_York'. Defaults to UTC.
`operation`	Yes	The datetime operation to perform

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses the tool's behavior: it performs three read-only datetime operations. It specifies input formats (ISO 8601, natural language) and format string patterns, giving the agent clear expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: it starts with a high-level summary, then breaks down each operation with examples. Each sentence adds value, though it could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters, three operations, and no output schema, the description covers input formats, required parameters per operation, and format string components. It is nearly complete, leaving little ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema already describes all parameters (100% coverage), the description adds meaning by explaining the context of each operation, how parameters combine, and the format string syntax. It goes beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's three operations: get current date/time, format a date, and calculate date difference. It distinguishes itself from sibling tools like calculator or random_gen by focusing specifically on datetime operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit instructions for when to use each operation (now, format, diff) and which parameters are required. However, it does not explicitly state when NOT to use this tool or list alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

random_genA

Generate random values. Operations: 'number' (random int in range, requires 'min' and 'max'), 'uuid' (UUID v4), 'password' (random password, optional 'length' and 'uppercase'/'symbols' flags), 'pick' (pick N items from a list, requires 'items' array and optional 'count'), 'shuffle' (shuffle a list, requires 'items' array).

ParametersJSON Schema

Name	Required	Description
`max`	No	Maximum value for 'number' operation (inclusive)
`min`	No	Minimum value for 'number' operation (inclusive)
`count`	No	Number of items to pick for 'pick' operation (default 1)
`items`	No	Array of items for pick/shuffle operations
`length`	No	Length for password (default 16)
`symbols`	No	Include symbols in password (default true)
`operation`	Yes	The random generation operation
`uppercase`	No	Include uppercase in password (default true)

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavioral traits: it explains each operation's process (e.g., 'number' generates random int in range, 'uuid' generates UUID v4) and defaults (password length 16, etc.). No destructive behavior is mentioned, which is consistent with a read-only generator.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence efficiently listing operations and their parameters. It is front-loaded with 'Generate random values.' While dense, it covers all necessary information without waste. A slightly more structured format would improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 operations, 8 parameters) and no output schema, the description provides sufficient context about each operation's inputs and behavior. It does not cover return values, but that is acceptable per guidelines. It is complete for a stateless random value generator.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaning by grouping operations and clarifying required parameters per operation (e.g., 'min' and 'max' for number, 'items' for pick/shuffle), which is not evident from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Generate random values' and enumerates five specific operations (number, uuid, password, pick, shuffle), providing a clear verb and resource. The tool is distinctly different from siblings like search, calculator, and text tools, so no sibling confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly tells when to use each operation via parameter requirements, but lacks explicit guidance on when to use this tool vs alternatives or when not to use it. Since siblings are unrelated, the context is adequate but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_agentA

Run a mini ReAct agent that can autonomously use all available tools to complete a task. The agent reasons step-by-step: it thinks about what to do, selects a tool, executes it, observes the result, and continues until it has enough information to give a final answer.

The agent supports multi-step tasks. Examples:

"Calculate 15 * 23 + sqrt(144)"
"Convert 100 cm to inches and also generate a UUID"
"What time is it in Asia/Shanghai?"
"Generate a 20-character password and tell me today's date"
"Search the web for the latest news about AI agents"
"Extract the content from https://example.com/article"

Available tool categories:

Built-in: calculator, text_stats, text_transform, unit_convert, datetime_info, random_gen
AnySearch (if connected): anysearch_search, anysearch_batch_search, anysearch_extract, anysearch_get_sub_domains

If LLM_API_KEY + LLM_BASE_URL + LLM_MODEL are all set (no defaults), the agent uses LLM-powered reasoning. Otherwise it uses a rule-based pattern matching engine.

ParametersJSON Schema

Name	Required	Description	Default
`task`	Yes	The task for the agent to complete. Be specific about what you want.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully convey behavior. It explains step-by-step reasoning and two execution modes, but does not disclose potential side effects (e.g., network calls if anysearch tools are used) or latency considerations. The behavioral description is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with paragraphs, bullet-point examples, and tool categories. It is front-loaded with the main purpose. While slightly long, every part adds context. Could be slightly more concise but is effectively organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity as an orchestrator, the description covers key aspects: purpose, reasoning process, execution modes, and dependencies (LLM config). It lists available tools. Missing details like error handling or limitations, but overall sufficient for an agent to understand usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'task' parameter, so baseline is 3. The description adds value through examples but does not elaborate on task format or constraints beyond what the schema says ('Be specific'). The added semantics are marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool runs a mini ReAct agent that autonomously uses all available tools. It provides a clear verb-resource pair and distinguishes itself from sibling tools (which are individual tools, while this is an orchestrator). Examples further clarify its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists example tasks and explains when to use the tool (multi-step tasks requiring reasoning). It also notes conditions for LLM vs rule-based mode. However, it does not explicitly state when not to use it or compare to alternatives beyond listing sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

text_statsA

Analyze text and return statistics: character count, word count, sentence count, paragraph count, average word length, and most frequent words.

ParametersJSON Schema

Name	Required	Description	Default
`text`	Yes	The text to analyze

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It states that the tool returns statistics, implying a read-only operation, but does not explicitly confirm it is non-destructive or side-effect-free. Lacks details on limitations or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action and immediately lists outputs. Every word earns its place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is reasonably complete. It explains inputs and outputs, though it could mention potential constraints (e.g., text length limits) to be fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for the single parameter 'text', so the description does not need to add parameter details. The description adds context on what statistics are computed, which indirectly helps understand the parameter's role, but does not surpass a baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Analyze text') and resource ('text'), and enumerates specific outputs (character count, word count, etc.), making it easy to understand what the tool does. No sibling tool duplicates this functionality, so differentiation is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives like 'text_transform' or when not to use it. The description does not provide context about prerequisites, preferred scenarios, or exclusions, leaving the agent to infer usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

text_transformA

Transform text in various ways. Operations: uppercase, lowercase, titlecase, reverse, trim, remove_duplicates (remove duplicate lines), sort_lines, count_substring (requires 'pattern' param), replace (requires 'pattern' and 'replacement' params).

ParametersJSON Schema

Name	Required	Description
`text`	Yes	The text to transform
`pattern`	No	Pattern for count_substring or replace operations
`operation`	Yes	The transformation to apply
`replacement`	No	Replacement text for replace operation

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It lists operations and param requirements but does not disclose whether operations are read-only or have side effects. However, the nature of text transformation is inherently non-destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with a clear bullet-like list. It is front-loaded with the purpose and each word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and 4 parameters, the description covers operations and param dependencies. It does not explain return values, but for a text transform the output is obvious.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by specifying which parameters are needed for which operations, e.g., 'count_substring (requires 'pattern' param)'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool transforms text in various ways and lists all specific operations. It distinguishes itself from sibling tools which are for different domains (search, calculation, date, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists operations and their required parameters (e.g., pattern for count_substring). It does not explicitly state when not to use this tool or give alternatives, but the context of sibling tools makes it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unit_convertA

Convert between units of the same category. Categories: length (mm, cm, m, km, inch, in, ft, yard, yd, mile, mi), weight (mg, g, kg, ton, t, oz, lb, pound), temperature (C, F, K), data (bit, byte, KB, MB, GB, TB). Example: convert 100 from 'cm' to 'inch'.

ParametersJSON Schema

Name	Required	Description
`to`	Yes	Target unit, e.g. 'inch', 'lb', 'F', 'MB'
`from`	Yes	Source unit, e.g. 'cm', 'kg', 'C', 'KB'
`value`	Yes	The value to convert

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It lists supported units and categories but omits details like error handling for mismatched categories or invalid units, which are important for an AI agent to anticipate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus an example, making it very concise. Key information is front-loaded with the purpose immediately stated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and the description covers categories and units adequately. No output schema exists, but the return format is implicitly clear for a conversion tool. Minor gap: no mention of precision or rounding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter. The description adds value by providing category groupings and a concrete example, enhancing understanding beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Convert between units of the same category' and provides specific categories and examples. It distinguishes itself from sibling tools like calculator or random_gen by focusing on unit conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the tool's purpose and gives an example, but it doesn't explicitly state when to use it over alternatives or provide any preconditions. However, the context is clear enough for most use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

11 tool updatesv1.0.1Jul 11, 2026
- First observedanysearch_batch_search
- First observedanysearch_extract
- First observedanysearch_get_sub_domains
- First observedanysearch_search
- First observedcalculator
- First observeddatetime_info
- First observedrandom_gen
- First observedrun_agent
- First observedtext_stats
- First observedtext_transform
- First observedunit_convert

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored 2026-07-11 09:25 across 11 tools

Disambiguation5/5

Each tool has a distinct purpose: search tools (anysearch_search, anysearch_batch_search, anysearch_extract, anysearch_get_sub_domains) are clearly separated, and utility tools (calculator, datetime_info, etc.) are unique. No two tools overlap in functionality.

Naming Consistency4/5

Tool names follow a pattern: Anysearch tools are prefixed with 'anysearch_', while built-in utilities use plain names like 'calculator'. This split is consistent within categories but introduces two naming conventions, which is a minor deviation.

Tool Count5/5

With 11 tools covering search, extraction, domain discovery, and common utilities (calculator, datetime, random, text operations, unit conversion), the count is well-scoped for a general-purpose assistant with web search capabilities.

Completeness4/5

The tool surface covers core operations: search (including batch and extraction), domain routing, and basic utilities. Minor gaps like file handling or more advanced text processing are absent, but the set is sufficiently complete for its stated purpose.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

agentwork-mcp A
io.github.ferm-ai
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Agent Orchestration Autonomous Agents App Automation
2
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
agentverse
io.github.doc2mcp
MCP server for agentverse documentation, generated by doc2mcp.
Agent Orchestration Documentation Access
24
H-Index A
ai.xr-utilities
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Search Documentation Access
2

Related MCP Servers

TOOL4LM
Research & Data Search Agent Orchestration
khanhs-234
F
license
C
quality
C
maintenance
A multi-tool MCP server that enhances local LLMs with web search, document reading, scholarly research, Wikipedia access, and calculator functions. Provides comprehensive tools for information retrieval and computation without requiring API keys by default.
Updated a year ago (2025-10-15 00:58 UTC)
22
1
-
Forage MCP Server
Autonomous Agents Developer Tools
isaac-levine
A
license
Not graded
quality
D
maintenance
An MCP server that enables AI agents to automatically discover, install, and learn to use new tools without manual configuration.
Updated 7 months ago (2026-02-21 23:02 UTC)
31
16
MIT
mcp-tool-server
File Systems Developer Tools Command Line
SyDd0
F
license
Not graded
quality
C
maintenance
A custom MCP server with 6 utility tools (file search, file reading, math calculation, JSON formatting, time query, system info) that demonstrates MCP protocol workflow and integrates with LangChain agents.
Updated 3 months ago (2026-06-25 17:08 UTC)
-
react-runtime
SanjoyDat1
-
license
Not graded
quality
Not graded
maintenance
MCP server implementing ReAct reasoning-acting loops with tools like search, lookup, and finish, supporting both fixture and OpenAI LLMs for offline-first, traceable agent execution.
Updated 2 months ago (2026-07-23 00:26 UTC)
-

Mini Agent MCP

一、这是什么

二、核心特性

三、架构总览

四、快速上手

4.1 MCP 客户端配置

4.2 .env 配置（fallback）

4.3 本地开发

4.4 验证安装

五、MCP 工具参考

5.1 唯一对外工具（外部 Agent 唯一可调）

5.2 内部工具（仅 Agent 可见，外部 tools/list 不可见）

基础工具（6 个 — 同步、确定性）

高级 pipeline（3 个）

记忆工具（3 个 — 持久化到 .memory/memories.json）

技能工具（2 个 — 持久化到 .skills/skills.json）

AnySearch 工具（4 个 — 懒加载）

六、AnySearch 内部工具

七、LLM 三模式 + Fallback

八、Hooks 系统（Yao 模式）

九、持久化层

9.1 Memory（.memory/memories.json）

9.2 Skill（.skills/skills.json）

十、DAG 工作流

十一、深度研究（deep_research）

十二、配置参考

12.1 全部环境变量

12.2 多供应商配置（providers.json）

12.3 内置供应商参考

十三、项目结构

十四、安全与设计理念

子路径导入（library 消费）

十五、CI 与本地复现

十五、许可证

十六、相关链接

Available Tools

When to use

Constraints

Examples

Single-domain batch (multiple sub_domains)

Multi-domain batch (after get_sub_domains with multiple domains)

Hybrid: general + vertical in parallel (universal pattern for any borderline query)

When to use — call extract after search whenever:

When NOT to use

Constraints

When to call — pick the domain(s) that match what the user is asking about:

Input — choose from the list above and pass via the domain or domains parameter:

Returns

CRITICAL: How to use results

Decision Tree (follow in order):

Path 1 — General query (first-class default for non-structured queries)

Path 2 — Vertical query (first-class default for structured / specialized queries)

Multi-Domain Strategy (CRITICAL for cross-domain queries)

Pattern 1 — Parallel domains (independent topics per domain)

Pattern 2 — Intersecting domains (SAME topic crosses multiple domains) — 🏆 THIS IS THE DEFAULT FOR AMBIGUOUS QUERIES

Examples

A — General query (Path 1 — RARE)

B — Single-domain vertical (Path 2)

C — Parallel multi-domain (Pattern 1: independent topics per domain)

C2 — Intersecting domains (Pattern 2: SAME topic viewed through multiple domain lenses)

D — Hybrid example 1: classical text + modern application

E — Hybrid example 2: financial concept + current data

Path 2 triggers (use vertical routing when the query has these signals):

Path 1 triggers (use general search directly, no get_sub_domains):

CRITICAL Rules:

Required params handling

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

4.2 `.env` 配置（fallback）

记忆工具（3 个 — 持久化到 `.memory/memories.json`）

技能工具（2 个 — 持久化到 `.skills/skills.json`）

9.1 Memory（`.memory/memories.json`）

9.2 Skill（`.skills/skills.json`）

12.2 多供应商配置（`providers.json`）