Provides web search capabilities with safety filters and caching, using Perplexity AI's API.
Enables interaction with SiYuan note-taking platform, including block-level content retrieval, full-text search, content updates, and database queries.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Martin MCP Toolbox search for recent breakthroughs in quantum computing"
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.
English README | 中文说明
一个基于 Model Context Protocol (MCP) 的多模态 AI 工具箱，集成了智谱 GLM、Pollinations.AI、思源笔记和 Perplexity 网络搜索四大平台的强大能力。
在使用 智谱 GLM 的 Claude Code 套餐时，我发现了一个限制：
Lite 版本价格更低，但不支持 图像/视频理解 和 联网搜索；
如果要获得这些能力，就必须升级到 Pro（¥100/月） 或 Max（¥200/月）；
但对很多开发者来说，仅仅为了这两个功能升级套餐，成本偏高。
我认为：
如果没有图像/视频理解，大模型就失去了"眼睛"；
如果没有联网搜索，大模型就失去了"更新知识的能力"；
这让 Lite 版本几乎成了一个"闭门造车"的模型，无法满足日常需求。
于是，我开发了这个 MCP 插件：
即使只用 GLM Lite 套餐，配合这个 MCP，也能为 Claude Code 装上眼睛（图像/视频理解）和 搜索引擎（联网搜索）；
让 Lite 用户也能享受"最新知识 + 多模态理解"的体验；
这大大提升了 Lite 套餐的性价比，也是我认为本项目最大的价值。
Related MCP server: SiYuan MCP Server
🖼️ 图片分析 - 使用 GLM-4.5V 模型进行图像识别和分析
🎬 视频分析 - 支持视频内容分析和理解
🎨 图片生成 - 使用 CogView-4 系列模型生成高质量图片
🖼️ 图片生成 - 支持多种模型和参数配置
📝 文本生成 - 智能文本生成和对话
🔊 音频生成 - 文字转语音，支持多种声音
👁️ 图片分析 - OpenAI 兼容的视觉分析能力
📚 块级内容获取 - 获取思源笔记块的 Kramdown 源码
🔍 全文搜索 - 支持复杂查询语法的笔记搜索
✏️ 内容更新 - 直接更新思源笔记块内容
🔍 基础搜索 - 快速检索并返回原始搜索结果
🧠 智能搜索 - 使用 Sonar 模型生成答案并提供引用
🛡️ 安全过滤 - 内置安全机制防止恶意内容
⚡ 缓存加速 - 智能缓存提高重复查询响应速度
🔧 灵活的环境变量配置
📝 完整的日志记录系统
🚀 轻量级，易于集成和部署
🛡️ TypeScript 类型安全
pnpm install访问 智谱AI开放平台 获取 API Key：
export GLM_API_KEY=your_glm_api_key_here访问 Perplexity AI 获取 API Key：
export PERPLEXITY_API_KEY=your_perplexity_api_key_here# GLM 模型配置
GLM_IMAGE_MODEL=glm-4.5v
GLM_VIDEO_MODEL=glm-4.5v
GLM_GENERATION_MODEL=cogview-3-flash
# 思源笔记配置（可选）
SIYUAN_API_TOKEN=your_siyuan_token
SIYUAN_API_BASE=http://127.0.0.1:6806
# 网络搜索配置（可选）
WEB_SEARCH_CACHE_TTL=30
WEB_SEARCH_RATE_LIMIT=5
WEB_SEARCH_RATE_WINDOW_MS=60000
WEB_SEARCH_RETRY_AFTER_MS=1000
WEB_SEARCH_TIMEOUT_MS=10000系统环境变量（推荐）
执行目录下的 .env 文件
项目根目录下的 .env 文件
pnpm dev注意: 开发模式使用 node --loader ts-node/esm 运行，确保 ES 模块导入正常工作。
pnpm buildpnpm start./build/index.js参数：
image_path (string): 图片文件路径
prompt (string): 分析提示文本
temperature (number, 可选): 采样温度 (0.0-1.0)
top_p (number, 可选): 采样参数 (0.0-1.0)
max_tokens (number, 可选): 最大输出令牌数
示例：
{
"image_path": "/path/to/image.jpg",
"prompt": "请详细描述这张图片的内容"
}参数：
video_url (string): 视频文件 URL
prompt (string): 分析提示文本
temperature (number, 可选): 采样温度 (0.0-1.0)
top_p (number, 可选): 采样参数 (0.0-1.0)
max_tokens (number, 可选): 最大输出令牌数
示例：
{
"video_url": "https://example.com/video.mp4",
"prompt": "分析这个视频的主要内容"
}参数：
prompt (string): 图片描述文本
quality (string, 可选): 图片质量 (hd/standard)
size (string, 可选): 图片尺寸
save_path (string, 可选): 图片保存路径
示例：
{
"prompt": "一只可爱的小猫咪，卡通风格",
"quality": "standard",
"size": "1024x1024",
"save_path": "./cat.png"
}参数：
prompt (string): 图片描述文本
model (string, 可选): 生成模型 (默认: flux)
width (number, 可选): 图片宽度 (64-2048)
height (number, 可选): 图片高度 (64-2048)
seed (number, 可选): 随机种子
nologo (boolean, 可选): 禁用 logo
private (boolean, 可选): 私有生成
enhance (boolean, 可选): 增强提示词
safe (boolean, 可选): 安全过滤
transparent (boolean, 可选): 透明背景
示例：
{
"prompt": "A beautiful landscape with mountains",
"model": "flux",
"width": 1024,
"height": 768
}参数：
prompt (string): 文本提示
model (string, 可选): 生成模型 (默认: openai)
temperature (number, 可选): 随机性 (0.0-3.0)
top_p (number, 可选): 核心采样 (0.0-1.0)
json (boolean, 可选): JSON 格式输出
system (string, 可选): 系统提示词
stream (boolean, 可选): 流式输出
示例：
{
"prompt": "写一首关于春天的诗",
"model": "openai",
"temperature": 0.8
}参数：
prompt (string): 要转换的文本
voice (string, 可选): 声音选择 (alloy/echo/fable/onyx/nova/shimmer)
model (string, 可选): 音频模型 (默认: openai-audio)
示例：
{
"prompt": "你好，欢迎使用我们的服务！",
"voice": "nova"
}参数：
image_path (string, 可选): 本地图片路径
image_url (string, 可选): 图片 URL
prompt (string): 分析提示文本
model (string, 可选): 分析模型 (默认: openai)
max_tokens (number, 可选): 最大输出令牌数
示例：
{
"image_path": "/path/to/image.jpg",
"prompt": "What's in this image?",
"model": "openai"
}参数：
q (string): 搜索查询文本
top_k (number, 可选): 返回结果数量 (1-20, 默认: 10)
time_range (string, 可选): 时间范围 (any/day/week/month/year, 默认: any)
site (string, 可选): 限制搜索站点
lang (string, 可选): 搜索语言 (默认: zh)
region (string, 可选): 搜索区域 (默认: CN)
safe_mode (boolean, 可选): 安全搜索模式 (默认: true)
include_snippets (boolean, 可选): 包含摘要片段 (默认: true)
示例：
{
"q": "人工智能最新发展",
"top_k": 5,
"time_range": "month",
"lang": "zh",
"region": "CN"
}参数：
q (string): 搜索查询文本
top_k (number, 可选): 返回结果数量 (1-20, 默认: 10)
time_range (string, 可选): 时间范围 (any/day/week/month/year, 默认: any)
site (string, 可选): 限制搜索站点
lang (string, 可选): 搜索语言 (默认: zh)
region (string, 可选): 搜索区域 (默认: CN)
safe_mode (boolean, 可选): 安全搜索模式 (默认: true)
include_snippets (boolean, 可选): 包含摘要片段 (默认: true)
operators (array, 可选): 搜索操作符 (OR/AND)
exclude_sites (array, 可选): 排除站点列表
from (string, 可选): 起始日期 (YYYY-MM-DD)
to (string, 可选): 结束日期 (YYYY-MM-DD)
dedupe (string, 可选): 去重策略 (none/domain/title, 默认: none)
aggregate (boolean, 可选): 聚合相似结果
engine (string, 可选): 搜索引擎 (raw_search/sonar_answer)
sonar_model (string, 可选): Sonar模型 (sonar/sonar-pro/sonar-reasoning/sonar-reasoning-pro/sonar-deep-research)
示例：
{
"q": "机器学习研究论文",
"top_k": 10,
"time_range": "year",
"exclude_sites": ["example.com", "spam.com"],
"from": "2023-01-01",
"to": "2023-12-31",
"dedupe": "domain",
"engine": "sonar_answer",
"sonar_model": "sonar-reasoning-pro"
}参数：
block_id (string|array): 单个块ID或块ID数组
示例：
{
"block_id": "20240825123456-1a2b3c4d"
}多块获取示例：
{
"block_id": ["20240825123456-1a2b3c4d", "20240825123456-5e6f7g8h"]
}参数：
block_id (string): 要更新的块ID
data (string): 新的Kramdown内容数据
data_type (string, 可选): 数据类型 (markdown/dom，默认: markdown)
示例：
{
"block_id": "20240825123456-1a2b3c4d",
"data": "# 新标题\n\n更新后的内容",
"data_type": "markdown"
}参数：
query (string): 搜索查询文本，支持完整全文查询语法
paths (array, 可选): 指定搜索路径
page (number, 可选): 分页页码
搜索语法示例：
{
"query": "机器学习 OR 深度学习",
"paths": ["/笔记/技术/"],
"page": 1
}高级查询示例：
{
"query": "NEAR(人工智能 算法, 10) -广告",
"page": 1
}支持的查询操作符：
OR - 逻辑或：包含任一即可
NEAR(词1 词2, N) - 邻近搜索：距离在N词内
AND - 逻辑与：必须同时包含
^词 - 权重提升：提高重要性
-词 - 排除：明确排除
(查询) - 分组：组合逻辑
参数：
stmt (string): SQL 查询语句，例如: SELECT * FROM blocks WHERE type = 'av' LIMIT 10
limit (number, 可选): 限制返回结果的数量
offset (number, 可选): 偏移量，用于分页查询
示例：
{
"stmt": "SELECT * FROM blocks WHERE type = 'av'",
"limit": 10
}高级查询示例：
{
"stmt": "SELECT b.id, b.content, a.name, a.value FROM blocks b JOIN attributes a ON b.id = a.block_id WHERE b.parent_id = '数据库块ID'",
"limit": 20,
"offset": 0
}参数：
stmt (string): SQL 查询语句，例如: SELECT * FROM blocks WHERE content LIKE '%content%' LIMIT 7
示例：
{
"stmt": "SELECT * FROM blocks WHERE type = 'd' LIMIT 5"
}高级查询示例：
{
"stmt": "SELECT distinct B.* from blocks as B join attributes as A on B.id = A.block_id where A.name like 'custom-dailynote-%' and B.type='d' and A.value >= '20231010' and A.value <= '20231013' order by A.value desc"
}项目包含完整的日志记录系统，所有工具调用都会记录到项目根目录的 mcpserver.log 文件中：
INFO: 工具调用和成功操作
ERROR: 错误和异常信息
DEBUG: 详细调试信息
WARN: 警告信息
src/
├── config/
│ ├── index.ts # GLM 配置和默认参数
│ └── pollinations.ts # Pollinations.AI 配置
├── tools/
│ ├── bigmodel/ # 智谱 GLM 工具
│ │ ├── image-analysis.ts # 图片分析工具
│ │ ├── video-analysis.ts # 视频分析工具
│ │ └── image-generation.ts # 图片生成工具
│ ├── pollinations/ # Pollinations.AI 工具
│ │ ├── image-generation.ts # 图片生成工具
│ │ ├── text-generation.ts # 文本生成工具
│ │ ├── audio-generation.ts # 音频生成工具
│ │ └── image-analysis.ts # 图片分析工具
│ ├── siyuan/ # 思源笔记工具
│ │ ├── block-kramdown.ts # 块级 Kramdown 获取工具
│ │ ├── database-query.ts # 数据库查询工具
│ │ ├── sql-query.ts # SQL 查询工具
│ │ ├── search.ts # 全文搜索工具
│ │ ├── client.ts # 思源 API 客户端
│ │ └── index.ts # 思源工具索引
│ └── web-search/ # 网络搜索工具
│ ├── web-search.ts # 网络搜索工具实现
│ ├── advanced-web-search.ts # 高级网络搜索工具实现
│ ├── client.ts # Perplexity API 客户端
│ ├── sonar-client.ts # Sonar 模型客户端
│ ├── cache.ts # 缓存实现
│ ├── rate-limiter.ts # 限速器实现
│ ├── security.ts # 安全工具
│ ├── errors.ts # 错误处理
│ └── types.ts # 类型定义
├── utils/
│ ├── helpers.ts # 通用助手函数
│ ├── common.ts # 响应格式化函数
│ └── logger.ts # 日志系统
└── index.ts # 主服务器入口，工具注册ISC
欢迎提交 Issue 和 Pull Request！
如有问题，请创建 Issue 或联系维护者。
本项目 fork 自 2234839 崮生 的项目，在此基础上进行了功能增强和扩展，已向原项目提交了 feature PR。
感谢原作者的杰出工作！🎉
在 web_search 的基础上，支持更复杂检索参数与结果整形；并可选启用 Sonar 直答（需要时才开）。
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | 查询语句 | |
| to | No | 结束日期 YYYY-MM-DD | |
| from | No | 起始日期 YYYY-MM-DD | |
| lang | No | ISO 语言代码，如 en, zh, fr | |
| site | No | 可选的site:domain 过滤 | |
| top_k | No | 返回结果数量 (1-20) | |
| dedupe | No | 去重策略 | domain |
| engine | No | 处理引擎 | raw_search |
| region | No | 地域/国家偏好，如 US, EU | |
| aggregate | No | 启用结果聚合 | |
| operators | No | 逻辑/语法运算，如 OR/AND/"exact" | |
| safe_mode | No | 启用安全搜索过滤 | |
| time_range | No | 时间范围过滤 | any |
| sonar_model | No | 特定的 Sonar 模型 | |
| exclude_sites | No | 要排除的站点 | |
| include_snippets | No | 包含文本片段 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions optional Sonar and result shaping but does not explain potential side effects, response formats, rate limits, or any safety implications. It lacks details on how the tool modifies results or what happens with Sonar models.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is easy to parse and contains no fluff. However, it is so brief that it sacrifices detail; still, it earns a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, enums, optional Sonar), the description is too minimal. It does not explain return values (no output schema), how result shaping works, nor when to choose different engines like sonar_answer vs raw_search. This leaves significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each of the 16 parameters. The description only generically mentions complex parameters without adding meaning to any specific parameter, so it sits at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states this is an advanced version of web_search, supporting complex retrieval parameters and result shaping, with optional Sonar direct answers. It clearly identifies the tool's function and distinguishes it from the sibling web_search by emphasizing 'advanced' features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies advanced_web_search should be used when complex retrieval parameters or Sonar are needed, but does not explicitly state when not to use it or compare with alternatives other than referencing web_search. The phrase '需要时才开' gives a hint to only enable Sonar when necessary, but no clear decision framework.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a video using GLM-4.5V model
| Name | Required | Description | Default |
|---|---|---|---|
| top_p | No | Top-p sampling parameter (0.0-1.0) | |
| prompt | Yes | Text prompt describing what to analyze in the video | |
| video_url | Yes | Publicly accessible URL of the video file to analyze | |
| max_tokens | No | Maximum output tokens | |
| temperature | No | Sampling temperature (0.0-1.0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It mentions the underlying model (GLM-4.5V) but does not disclose behaviors such as output format, latency, cost, or any limitations of video analysis.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, which is structurally clean. However, it is too brief to convey essential context and borders on under-specification, which is not conciseness but rather incompleteness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are no annotations and no output schema, the description should compensate by explaining what the tool returns, any prerequisites (e.g., video URL format), and typical use cases. It provides none of this, making it insufficient for an AI agent to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented with meaningful descriptions. The tool description adds no extra information about parameters, which is acceptable since the schema fully covers them. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Analyze') and a specific resource ('a video'), which clearly distinguishes it from image-related tools like read_image and pollinations_analyze_image. However, it does not specify what kind of analysis is performed or what aspects of the video are examined, making it somewhat generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. The sibling tools include image analysis and text generation, but the description does not explain when video analysis is appropriate or mention any alternatives to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image from text prompt using CogView-4 model
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Image size. Default: 1024x1024 | |
| prompt | Yes | Text description of the image to generate | |
| quality | No | Image quality. hd: higher quality but slower (20s), standard: faster (5-10s). Default: standard | |
| save_path | No | Local path to save the generated image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure, but it only states the basic generation action. It does not mention output format, return behavior, saving semantics, costs, rate limits, or any side effects. The timing/quality trade-off is present in the schema, but the description itself adds no behavioral context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no fluff, front-loaded with the core action and resource. It is appropriately sized for a tool whose parameters are fully documented in the schema, and every word contributes to meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generation tool with no output schema, the description should clarify what the tool returns or saves (e.g., path, URL, base64). The presence of a save_path parameter implies saving, but the description does not confirm this or mention the return value. Combined with sibling ambiguity, the description is incomplete for an agent to invoke it correctly and handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no new parameter meaning beyond schema, but it does not mislead either. The model name ('CogView-4') is context not directly tied to parameters, but does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a text-to-image generation tool using the CogView-4 model, with a specific verb ('generate') and resource ('image from text prompt'). However, it does not distinguish itself from the sibling tool pollinations_generate_image, which also generates images, so it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the alternative image generation tool or other siblings. It does not mention preferred use cases, exclusions, or conditions that would make this tool the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get kramdown source code of one or multiple SiYuan note blocks
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | Single block ID or array of block IDs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It correctly indicates a read operation via 'Get' and specifies the output format ('kramdown source code'). However, it does not disclose return structure (e.g., how multiple IDs are returned) or error behavior, which is a noticeable gap given no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that leads with the verb and object, with no redundant or filler content. Every word contributes to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter read operation, the description adequately covers purpose and parameters. It lacks explicit guidance on when to prefer this over sibling tools and omits return format details, but within the tool's low complexity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with block_id fully described in the schema. The description adds no extra semantic detail beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('kramdown source code'), and the target ('SiYuan note blocks'), distinguishing it from sibling tools like update_block or siyuan_query_sql. It also accurately notes the capability to fetch one or multiple blocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: when the agent needs raw kramdown source for SiYuan blocks. It doesn't explicitly exclude alternatives like siyuan_query_sql or search, but the purpose is clear enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze an image using Pollinations.AI Vision API
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model for vision analysis (default: openai) | |
| prompt | Yes | Text prompt describing what to analyze in the image | |
| image_url | No | URL of the image to analyze | |
| image_path | No | Path to the local image file | |
| max_tokens | No | Maximum output tokens |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavioral traits, but it only states that it uses Pollinations.AI Vision API. It does not disclose network requirements, whether both image_url and image_path are supported for different scenarios, output format, or any side effects. The description is minimal and leaves critical behavior unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It directly states the tool's purpose and the API used, making it highly concise and front-loaded. Every word contributes value, exemplifying efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no output schema, and no annotations. The description provides only a high-level summary and lacks information about the return value, how to choose between image_url and image_path, model options, or potential errors. Given the tool's complexity, the description is under-specified and incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 5 parameters, and the schema description coverage is 100%. The tool description itself adds no parameter-specific meaning, so it does not enhance the schema. A baseline score of 3 is appropriate when the schema already documents all parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Analyze' and names the resource 'image', clearly stating the core action. It also identifies the underlying API (Pollinations.AI Vision API), adding useful context. However, it does not explicitly differentiate itself from sibling tools like 'read_image' or 'generate_image', so it lacks clear sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description neither mentions common use cases nor excludes others, such as using 'read_image' for local file reading or 'generate_image' for creation. There are no prerequisites or context clues beyond the basic one-line statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate speech audio from text using Pollinations.AI API
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model for audio generation (default: openai-audio) | |
| voice | No | Voice to use for synthesis (default: alloy) | |
| prompt | Yes | Text to synthesize into speech |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It states the external API usage but fails to disclose return format, rate limits, authentication needs, or any side effects beyond generation, leaving the agent without critical operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently states the tool's action and API. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema is thorough, but the absence of an output schema and annotations means the description should clarify what the agent receives (audio URL, file, etc.). It doesn't, leaving a gap in operational completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions and defaults. The description doesn't add extra parameter semantics beyond linking 'text' to the prompt parameter, which is sufficient given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generate'), identifies the resource ('speech audio from text'), and names the API ('Pollinations.AI'), clearly distinguishing it from sibling image/text generation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates the tool is for text-to-speech generation, providing enough context for selection. However, it doesn't mention exclusions or explicitly reference alternatives like generate_image or pollinations_generate_text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image using Pollinations.AI API
| Name | Required | Description | Default |
|---|---|---|---|
| safe | No | Strict NSFW filtering (default: false) | |
| seed | No | Seed for reproducible results | |
| model | No | Model for image generation (default: flux) | |
| width | No | Image width in pixels (default: 1024) | |
| height | No | Image height in pixels (default: 1024) | |
| nologo | No | Disable Pollinations logo overlay (default: false) | |
| prompt | Yes | Text description of the image to generate | |
| enhance | No | Enhance prompt using LLM for more detail (default: false) | |
| private | No | Prevent image from appearing in public feed (default: false) | |
| transparent | No | Generate with transparent background (gptimage model only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Generate an image,' providing no behavioral details such as output format, side effects, rate limits, or public feed implications. This is a significant gap for a tool with 10 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence and front-loaded, but it is under-specified given the tool's complexity. It is concise but lacks needed information to be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema or annotations, the description is insufficient. It only states the purpose without covering behavior, parameter semantics, or usage context, making it incomplete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates an image using the Pollinations.AI API, which distinguishes it from text/audio tools. However, it doesn't explicitly differentiate from the sibling 'generate_image' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no exclusions, and no context. It only states the basic function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate text using Pollinations.AI API
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return response as JSON string (default: false) | |
| seed | No | Seed for reproducible results | |
| model | No | Model for text generation (default: openai) | |
| top_p | No | Nucleus sampling parameter (0.0-1.0) | |
| prompt | Yes | Text prompt for the AI | |
| stream | No | Enable streaming responses (default: false) | |
| system | No | System prompt to guide AI behavior | |
| private | No | Prevent response from appearing in public feed | |
| temperature | No | Controls randomness (0.0-3.0) | |
| presence_penalty | No | Penalizes tokens based on presence | |
| frequency_penalty | No | Penalizes tokens based on frequency |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing behavioral traits. It only restates the action without mentioning rate limits, streaming behavior, privacy implications, or response format. This provides no transparency beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or redundant information. It is appropriately brief, though it could benefit from additional structure or elaboration given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, no annotations, and no output schema, the description is severely incomplete. It fails to explain any behavioral context, return values, or usage scenarios, making it inadequate for an agent to understand the tool's full capabilities and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 11 parameters have descriptions in the schema. The tool description adds no additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates text using the Pollinations.AI API. This distinguishes it from sibling tools like pollinations_generate_image and pollinations_generate_audio, which generate other media types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or alternative tools, leaving the agent to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze an image using GLM-4.5V model
| Name | Required | Description | Default |
|---|---|---|---|
| top_p | No | Top-p sampling parameter (0.0-1.0) | |
| prompt | Yes | Text prompt describing what to analyze in the image | |
| image_path | Yes | Path to the local image file | |
| max_tokens | No | Maximum output tokens | |
| temperature | No | Sampling temperature (0.0-1.0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states 'Analyze an image' without revealing whether the operation is read-only, what kind of output to expect, or any side effects. This lacks critical behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It communicates the core function efficiently and is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and a minimal description. It does not explain what kind of analysis results are returned, how to formulate prompts, or any context for selecting this over similar image-analysis siblings. This leaves a significant completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 5 parameters with descriptions, so the baseline is 3. The description does not add any parameter-specific meaning, but it doesn't need to because the schema is fully self-documenting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Analyze' and identifies the resource as 'image', with the model name GLM-4.5V adding specificity. It clearly states what the tool does, but does not explicitly differentiate from sibling tool 'pollinations_analyze_image', which also analyzes images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like pollinations_analyze_image or analyze_video. There is no mention of use cases, exclusions, or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
思源数据库查询工具 - 执行 SQLite 查询语句来查询思源笔记的数据库（树形视图/属性视图）
此工具允许您查询思源笔记中的数据库（也称为树形视图或属性视图）。您可以使用标准的 SQLite 语法来查询数据库中的数据。
blocks: 内容块表
attributes: 属性表
refs: 引用表
id: 内容块 ID
parent_id: 父块 ID
root_id: 文档块 ID
box: 笔记本 ID
path: 内容块路径
hpath: 人类可读路径
name: 内容块名称
alias: 别名
memo: 备注
tag: 标签
content: 内容文本
fcontent: 第一个子块内容
markdown: Markdown 格式内容
length: 内容长度
type: 块类型 (d:文档, h:标题, p:段落, l:列表, t:表格, b:引述, s:超级块, c:代码块, m:数学公式, av:数据库)
subtype: 子类型
ial: 内联属性列表
sort: 排序权重
created: 创建时间
updated: 更新时间
id: 属性 ID
name: 属性名称 (自定义属性需加 custom- 前缀)
value: 属性值
type: 类型
block_id: 块 ID
root_id: 文档 ID
box: 笔记本 ID
path: 文档路径
id: 引用 ID
def_block_id: 被引用块 ID
def_block_root_id: 被引用块文档 ID
def_block_path: 被引用块路径
block_id: 引用块 ID
root_id: 引用块文档 ID
box: 笔记本 ID
path: 引用块路径
content: 引用锚文本
查询所有数据库块: SELECT * FROM blocks WHERE type = 'av' LIMIT 10
查询特定数据库中的记录: SELECT * FROM blocks WHERE parent_id = '数据库块ID' LIMIT 20
查询具有特定属性的块: SELECT * FROM attributes WHERE name = 'custom-status' AND value = '完成'
查询数据库中的记录及其属性: SELECT b.id, b.content, a.name, a.value FROM blocks b JOIN attributes a ON b.id = a.block_id WHERE b.parent_id = '数据库块ID' LIMIT 10
只允许执行 SELECT 查询语句
禁止执行修改数据的语句 (INSERT, UPDATE, DELETE, DROP等)
查询结果会自动限制返回的行数以防止过大响应
| Name | Required | Description | Default |
|---|---|---|---|
| stmt | Yes | SQL 查询语句，例如: SELECT * FROM blocks WHERE type = 'av' LIMIT 10 | |
| limit | No | 限制返回结果的数量 | |
| offset | No | 偏移量，用于分页查询 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses that only SELECT statements are allowed, prohibits modification statements, and mentions automatic result limiting. This is strong behavioral transparency, though it does not specify the exact result limit or error behavior on invalid queries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (功能说明, 支持的表, 表结构, 示例, 安全注意事项). It is front-loaded with a concise summary, and every section serves a purpose. Despite its length, it remains focused and informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a SQL query tool with no output schema, the description is remarkably complete: it covers the tool's purpose, supported tables, full table structures, practical examples, and security constraints. While it doesn't specify the return format, the examples and schema make the expected behavior clear enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds significant value by documenting the underlying table schemas (blocks, attributes, refs) and providing SQL examples, which helps construct valid 'stmt' values beyond the schema's brief parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes SQLite queries against the SiYuan database (tree/attribute views), with a specific verb and resource. However, it does not distinguish itself from the sibling tool 'siyuan_query_sql', which likely has overlapping functionality, so it misses the sibling differentiation required for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear functional context and multiple usage examples, indicating when to use the tool (to query databases). However, it does not mention any alternative tools or exclusions (e.g., when to use siyuan_query_sql instead), so it lacks explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
思源 SQL 查询工具 - 执行 SQLite 查询语句
你是思源小助手，你需要根据用户需求，编写符合思源笔记数据库结构的 SQL 查询语句。在必要时，解释查询结果的含义和用途。
要求 SQL 语法规范：
在默认的情况下，用户可以在思源的嵌入块中输入 SQL 代码查询，此时 SQL 查询语句必须以 select * from blocks 开头：只允许查询 block 表，且不允许单独查询字段 面向开发者的高级用法：用户还可以调用后端 API 接口，发送 SQL 查询，此时是可以使用更普遍的 SQL 语法结构的（查询别的表，返回特定字段） 使用 SQLite 的语法，如 strftime 函数处理时间。 默认情况下，查询结果最多返回 64 个块，除非明确指定了 limit xxx 输出：将查询语句放在一个 ```SQL 的 markdown 代码块当中，方便用户直接复制
表结构 blocks 表:
id: 内容块 ID，格式为 时间-随机字符，例如 20210104091228-d0rzbmm。
parent_id: 双亲块 ID，格式同 id
root_id: 文档块 ID，格式同 id
box: 笔记本 ID，格式同 id
path: 内容块所在文档路径，例如 /20200812220555-lj3enxa/20210808180320-abz7w6k/20200825162036-4dx365o.sy
hpath: 人类可读的内容块所在文档路径，例如 /0 请从这里开始/编辑器/排版元素
name: 内容块名称
alias: 内容块别名
memo: 内容块备注
tag: 标签，例如 #标签1 #标签2# #标签3#
content: 去除了 Markdown 标记符的文本
fcontent: 存储容器块第一个子块的内容
markdown: 包含完整 Markdown 标记符的文本
length: markdown 字段文本长度
type: 内容块类型
d: 文档, h: 标题, m: 数学公式, c: 代码块, t: 表格块, l: 列表块, b: 引述块, s: 超级块，p：段落块，av：树形视图（俗称数据库，注意区分，这只是一个内容块的叫法） subtype: 特定类型的内容块还存在子类型
标题块的 h1 到 h6 列表块的 u (无序), t (任务), o (有序) ial: 内联属性列表，形如 {: name="value"}，例如 {: id="20210104091228-d0rzbmm" updated="20210604222535"}
sort: 排序权重，数值越小排序越靠前
created: 创建时间，格式为 YYYYMMDDHHmmss，例如 20210104091228
updated: 更新时间，格式同 created
refs 表:
id: 引用 ID，格式为 时间-随机字符，例如 20211127144458-idb32wk def_block_id: 被引用块的块 ID，格式同 id def_block_root_id: 被引用块所在文档的 ID，格式同 id def_block_path: 被引用块所在文档的路径，例如 /20200812220555-lj3enxa/20210808180320-fqgskfj/20200905090211-2vixtlf.sy block_id: 引用所在内容块 ID，格式同 id root_id: 引用所在文档块 ID，格式同 id box: 引用所在笔记本 ID，格式同 id path: 引用所在文档块路径，例如 /20200812220555-lj3enxa/20210808180320-fqgskfj/20200905090211-2vixtlf.sy content: 引用锚文本 attributes 表:
id: 属性 ID，格式为 时间-随机字符，例如 20211127144458-h7y55zu
name: 属性名称
注意：思源中的用户自定义属性必须加上 custom- 前缀 例如 name 是块的内置属性，但 custom-name 就是用户的自定义属性了 value: 属性值
type: 类型，例如 b
block_id: 块 ID，格式同 id
root_id: 文档 ID，格式同 id
box: 笔记本 ID，格式同 id
path: 文档文件路径，例如 /20200812220555-lj3enxa.sy。
查询要点提示 所有 SQL 查询语句如果没有明确指定 limit，则会被思源查询引擎默认设置 limit 64
块属性格式相关
块 ID 格式统一为 时间-随机字符, 例如 20210104091228-d0rzbmm 块的时间属性，如 created updated 的格式为 YYYYMMDDHHmmss 例如 20210104091228 块之间的关系
层级关系：块大致可以分为
内容块（叶子块）：仅包含内容的块，例如段落 p，公式块 m，代码块 c，标题块 h，表格块 t 等
内容块的 content 和 markdown 字段为块的内容 容器块：包含其他内容块或者容器块的块，例如 列表块 l，列表项块 i，引述块/引用块 b，超级块 s
每个块的 parent_id 指向他直接上层的容器块 容器块的 content 和 markdown 字段为容器内所有块的内容 文档块：包含同一文档中所有内容块和容器块的块，d
每个块的 root_id 指向他所在的文档 容器块的 content 字段为文档的标题 引用关系：当一个块引用了另一个块的时候，会在 refs 表中建立联系
如果有多个块引用了同一个块，那么对这个被引用的块而言，这些引用它的块构成了它的反向链接（反链） 所有引用关系被存放在 ref 表当中；使用的时候将 blocks 表和 ref 表搭配进行查询 Daily Note：又称日记，每日笔记，是一种特殊的文档块
daily note 文档有特殊属性：custom-dailynote-=；被标识了这个属性的文档块(type='d')，会被视为是对应日期的 daily note 文档 例如 custom-dailynote-20240101=20240101 的文档，被视为 2024-01-01 这天的 daily note 文档 请注意！ daily note （日记）是一个文档块！如果要查询日记内部的内容，请使用 root_id 字段来关联日记文档和内部的块的关系 书签：含有属性 bookmark=<书签名> 的块会被加入对应的书签
SQL 示例 查询所有文档块
select * from blocks where type='d' 查询所有二级标题块
select * from blocks where subtype = 'h2' 查询某个文档的子文裆
select * from blocks where path like '%/<当前文档id>/%' and type='d' 随机漫游某个文档内所有标题块
SELECT * FROM blocks WHERE root_id LIKE '<文档 id>' AND type = 'h' ORDER BY random() LIMIT 1 查询含有关键词「唯物主义」的段落块
select * from blocks where markdown like '%唯物主义%' and type ='p' ORDER BY updated desc 查询过去 7 天内没有完成的任务（任务列表项）
注：思源中，任务列表项的 markdown 为 * [ ] Task text 如果是已经完成的任务，则是 * [x] Task Text
SELECT * from blocks WHERE type = 'l' AND subtype = 't' AND created > strftime('%Y%m%d%H%M%S', datetime('now', '-7 day')) AND markdown like'* [ ] %' AND parent_id not in ( select id from blocks where subtype = 't' ) 查询某个块所有的反链块（引用了这个块的所有块）
select * from blocks where id in ( select block_id from refs where def_block_id = '<被引用的块ID>' ) limit 999 查询某个时间段内的 daily note（日记）
注意由于没有指定 limit，最大只能查询 64 个
select distinct B.* from blocks as B join attributes as A on B.id = A.block_id where A.name like 'custom-dailynote-%' and B.type='d' and A.value >= '20231010' and A.value <= '20231013' order by A.value desc; 查询某个笔记本下没有被引用过的文档，限制 128 个
select * from blocks as B where B.type='d' and box='<笔记本 BoxID>' and B.id not in ( select distinct R.def_block_id from refs as R ) order by updated desc limit 128
| Name | Required | Description | Default |
|---|---|---|---|
| stmt | Yes | SQL 查询语句，例如: SELECT * FROM blocks WHERE content LIKE '%content%' LIMIT 7 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavior disclosure. It details constraints (only block table in default mode, default LIMIT), output formatting (markdown code block), and provides extensive schema documentation. It implies read-only usage but does not explicitly mention error handling or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose and requirements, then organized into schema documentation, query tips, and examples. It is lengthy but well-structured, with each section contributing practical value for writing SQL. It could be tightened but is not redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not explain the tool's return value format, which is a notable gap. It also omits explicit read-only guarantees. However, it is highly comprehensive for writing correct queries, covering schemas, syntax constraints, and examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already describes stmt (100% coverage), the description goes far beyond by documenting the blocks/refs/attributes schemas, field meanings, and offering multiple practical query examples. This greatly enriches the meaning of what a user can pass as a statement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '思源 SQL 查询工具 - 执行 SQLite 查询语句', clearly stating it executes SQLite queries against SiYuan. It distinguishes itself from siblings like siyuan_search_blocks by emphasizing SQL syntax and database schema details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use embedded-block SQL (must start with select * from blocks) versus advanced API mode, and notes the default LIMIT 64. It provides clear usage context, though it does not explicitly name alternative tools for different query types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for blocks in SiYuan notes using full-text search
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| paths | No | Specific paths to search within | |
| query | Yes | Search query text,支持 Full-text Query Syntax 语法 ### 基本操作符 1. **OR** - 逻辑或：包含任一即可（优先使用，保证搜索结果） 2. **NEAR(词1 词2, N)** - 邻近搜索：距离在N词内，如 NEAR(机器学习 算法, 10) 3. **AND** - 逻辑与：必须同时包含（谨慎使用，容易导致零结果） 4. **^词** - 权重提升：提高重要性，如 ^深度学习 5. **-词** - 排除：明确排除，如 -广告 6. **(查询)** - 分组：组合逻辑，如 (机器学习 OR 深度学习) ## 重要原则 ### 避免"零结果"的策略 1. **优先使用 OR**：对同义词、相关词用 OR 连接 2. **谨慎使用 AND**：只在确定必须同时出现时使用 3. **放宽 NEAR 距离**：使用 10-15 的较大距离 4. **多层次查询**：主查询 OR (备选查询1) OR (备选查询2) 5. **避免过度限制**：不要堆砌太多 AND 条件 ### 查询构建优先级 1. **核心词 OR 相关词**：保证基础搜索结果 2. **NEAR(核心词 相关词, 10-15)**：提升精确度但不过度限制 3. **选择性 AND**：只对绝对必要的条件使用 AND 4. **权重提升**：对最重要概念使用 ^ 5. **排除干扰**：只对明显无关内容使用 - |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states a basic search operation. It does not disclose potential limitations, auth requirements, pagination behavior, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. Every word contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what the search returns and how pagination works (page parameter). It does neither, leaving the expected response format and behavior unclear for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have detailed descriptions in the schema (100% coverage), including an extensive query syntax guide. The tool description itself adds no semantic detail beyond naming full-text search, so the schema carries the parameter explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('blocks in SiYuan notes'), and the method ('full-text search'), which distinguishes it from the sibling tool 'siyuan_query_sql' that uses SQL queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for full-text search needs but does not provide explicit when-to-use or alternatives comparison. It does not mention exclusions such as 'use siyuan_query_sql for structured queries'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a SiYuan note block with new content while preserving IAL metadata
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | New Kramdown content data to update the block with | |
| block_id | Yes | ID of the SiYuan block to update | |
| preserve_id | No | Whether to preserve ID attributes (default: true) | |
| preserve_ial | No | Whether to preserve IAL attributes (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does state that IAL metadata is preserved, which is a useful behavior, but it omits critical aspects like whether the update is destructive, whether it can partially fail, any permission requirements, or what happens to other block properties. The mention of preservation is also partially redundant with the preserve_ial parameter, so the added transparency value is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise, front-loaded with the action, and includes a meaningful qualifier. No wasted words, and it covers the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is minimal. It does not explain return values, error behavior, prerequisites (like whether the block_id must exist), or side effects. The presence of two optional boolean parameters (preserve_id, preserve_ial) is not elaborated, and the description does not mention how they affect the update. This leaves significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all four parameters described individually. The description adds no extra semantic value beyond the schema: 'new content' repeats the data parameter's description, and 'preserving IAL metadata' echoes the preserve_ial parameter. Baseline of 3 is appropriate since the schema already carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a SiYuan note block') and the resource ('note block'), with a specific qualifier about preserving IAL metadata. This is distinct from all sibling tools, which are read/search/generate operations, making the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. Sibling tools exist for reading blocks (get_block_kramdown) and searching (siyuan_search_blocks), but the description does not contrast with them or indicate the appropriate context for an update operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
快速检索并返回原始搜索结果（不做自动成文）。
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | 查询语句 | |
| lang | No | ISO 语言代码，如 en, zh, fr | |
| site | No | 可选的site:domain 过滤 | |
| top_k | No | 返回结果数量 (1-20) | |
| region | No | 地域/国家偏好，如 US, EU | |
| safe_mode | No | 启用安全搜索过滤 | |
| time_range | No | 时间范围过滤 | any |
| include_snippets | No | 包含文本片段 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It discloses that results are raw and that no automatic synthesis occurs, which is useful behavioral context. However, it omits output format, pagination, rate limits, and any side-effect warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, compact sentence in Chinese conveys the core functionality and a key exclusion. It is front-loaded and every word earns its place, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the rich schema, the description is too terse for the tool's context: no output schema, no annotations, and a sibling tool with similar purpose. It lacks guidance on result format, limitations, and relationship to advanced_web_search, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all 8 parameters, so the description does not need to explain them. The description adds no parameter-specific semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs quick web search and returns raw results, explicitly noting it does not generate articles. This distinguishes it from content-generation tools but does not differentiate it from the sibling 'advanced_web_search'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives like advanced_web_search. The phrase 'raw search results' implies use when structured/summarized output is not needed, but no direct comparison or exclusion is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0advanced_web_searchanalyze_videogenerate_imageget_block_kramdownpollinations_analyze_imagepollinations_generate_audiopollinations_generate_imagepollinations_generate_textread_imagesiyuan_database_querysiyuan_query_sqlsiyuan_search_blocksupdate_blockweb_searchSeveral tools have overlapping purposes: siyuan_query_sql and siyuan_database_query both execute SQLite queries on the same tables, read_image and pollinations_analyze_image both analyze images, generate_image and pollinations_generate_image both generate images, and web_search/advanced_web_search are near-duplicates. This causes confusion about which tool an agent should select for a given task.
Naming is mixed: some tools follow verb_noun (read_image, update_block) while others use noun_verb (web_search, siyuan_database_query). Prefixes like siyuan_ and pollinations_ are inconsistent, and 'advanced_web_search' does not follow the verb-first pattern of its counterpart.
14 tools is within the reasonable range, but the server spans multiple unrelated domains (SiYuan notes, media AI, web search). The count is not excessive, though it feels like a collection of utilities rather than a focused toolset.
For SiYuan notes, query, search, get, and update are covered but create/delete operations are missing. The media tools cover image generation/analysis and video analysis but lack video generation or audio analysis. Web search is adequately covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Turn any LLM multimodal; generate images, voices, videos, 3D models, music, and more.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/2234839/mcpserver'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
