Skip to main content
Glama
Seom-ingit

vision_kit

by Seom-ingit
OverviewSchemaRelated ServersScoreDiscussions
Python

English · 简体中文

👁️ vision_kit

Make your AI agent a math tutor. · 把 AI 变成能教你做题的家教。

看数学 / 几何题图，靠的不是看图，而是「看对」：从图里抽取向量、矩阵、坐标、角度， 自动检查维度是否一致、几何是否自洽，漏了重试补全、大图自动分块。 结果不对就读不出来——而不是把错题当真。任意文本模型，接上它就能"看见"数学图。

Python · OpenAI 兼容视觉模型 · MCP · DeepSeek Harness · opencode

它是唯一会「算」的视觉插件： 竞争的插件都只会「看」（通用看图问答）， vision_kit 在 VLM 输出之后加上一层确定性校验—— 三角形内角和 ≠ 180°、向量加法不匹配、矩阵维度不符、负值/越界， 任一触发就采样重试，重试耗尽后把 ✓ / ✗ 逐条返回给 agent，让它能发现 「VLM 读错数」而不是把错题当真。

对抗演示：VLM 自信地错 vs vision_kit 拦截

对抗样本：图上标注 ∠A=60° ∠B=60° ∠C=70°（内角和 190°）。纯 VLM 直接采信并输出；vision_kit 的校验层发现内角和 ≠ 180°，返回 ✗ GEOMETRY_INCONSISTENT 并定向重试——错误成为显式信号。

能力一览

四段式闭环：读图 → 校验 → 重试 → 诊断

能力

说明

结构化识别

提取向量 / 矩阵 / 坐标 / 角度 / 未知量等数字标注

图元 DOM

点 / 线段 / 角 / 圆 / 四边形 类型化图元（figures），引用完整性校验（端点/顶点/圆心/四边形顶点必须已定义）

维度一致性

同组向量 / 矩阵自动校验维度，发现漏数自动采样重试补齐

几何自洽校验

三角内角和、向量加法、矩阵乘法维度、线段长度 vs 端点距离、三角形不等式、勾股定理、圆定理（圆上点到圆心距离=半径、直径对直角）、相似三角形、平行四边形对边相等、函数图对称轴、负值/值域 —— 纯逻辑，零外部依赖

定向补漏重试

校验失败的具体规则（维度/角度和/向量加法/边长…）回流成定向重试提示，第 2/3 次采样重试带着「错在哪」去读图

置信度 / 诊断

每条结果带 diagnostics：错误码（DIMENSION_MISMATCH / GEOMETRY_INCONSISTENT / NO_NUMERIC_CONTENT…）+ 整体/逐值置信度 + 重试次数，agent 可据错误码行动

图像预处理

小图自动放大（保证数字清晰）、超大图 2×2 带重叠分块后合并再校验（跨块向量/几何关系不丢失）；describe 超大图自动分块描述

渲染回写

抽取结果用 PIL 还原成 PNG（round-trip），供人 / 模型目视比对抓幻觉

TikZ 输出

DOM → 可编译 LaTeX/TikZ 片段（--tikz），题图可"照着重建"用于排版/复刻

统计图 → 数据表

柱状 / 折线 / 饼图 → 类别 + 系列数值，带长度对齐 / 百分比求和≈100 / 非负校验（--mode stats）

基准 + 回归快照

benchmark/ 三套基准：12 张合成题图（数值准确率/召回/幻觉/一致性/几何自洽/重试率，--baseline 量化校验层增益）+ 6 张对抗注入集（矛盾标注，校验层防护率）+ 12 张困难集（扰动图，补漏重试价值）；tests/snapshots/ 数值级回归，CI 自动比对

多端接入

同一个引擎多端复用：DSH 插件 / opencode 插件 / MCP / CLI

Related MCP server: Agentic-AI-Planning-And-Reasoning-MCP

🤏 怎么选：describe 还是 extract？

vision_kit 的两个工具分工不同，选对才能发挥各自优势：

场景

推荐工具

说明

非数学/几何图（照片、场景图、流程图、电气/电路示意图、通用图片问答）

describe

只看图返回自然语言描述/回答问题，泛化能力强，不会硬套结构

带数值标注的数学题图（向量 / 矩阵 / 点坐标 / 角度 / 长度 / 未知量）

extract

结构化提取 + 维度一致 + 几何自洽校验，是它最擅长的

想两者都要

both

先描述全貌，再结构提取

几个需要知道的边界：

  • extract 是"数学图专用"，它强制按向量/矩阵/坐标输出结构。对没有这类结构的图（如电气布局、UI、照片），模型可能为凑格式而编造不存在的向量——这种情况请改用 describe。

  • describe 不看结构，适合通用看图；但对带精确数字标注的题图，它不会做维度/几何校验，拿不到可信的结构化结果。

  • 判断一张图"算不算数学题图"：画面上是否要精确读出成组的数字序列（向量、矩阵、坐标、角度）。是 → extract；否 → describe。

一张（黑底）电气原理图测试：describe 能准确识别三相电源、PLC、各类开关/端子；若用它跑 extract，因图中无向量/矩阵标注，可能得到编造的假向量——这正是"非数学图请用 describe"的典型场景。

对比：为什么是 vision_kit

插件 / 项目

定位

vision_kit 的差异

dsh-vision (view_image)

通用看图问答

✅ 唯一做结构化数学/几何图的结构输出

dsh-tool-see-image (see_image)

通用看图

✅ 有维度校验、几何自洽、补漏重试

dsh-plugin-deepeye

通用看图

✅ 有确定性自洽校验，非纯描述

dsh-vision-toolkit

OCR / UI 还原

✅ 面向数学标注，校验数值自洽

一句话：「读图 + 几何自洽校验」的组合目前无人做。vision_kit 把校验放在 VLM 输出之后—— 纯逻辑、可测试、可评测，不依赖特定的视觉模型能力。

📊 基准数据（12 张合成题图 · qwen3-vl-flash）

开源基准数字卡

首份真实基准已发布（benchmark/REPORT.md，可复现）：

指标

值

数值准确率

97.2%（35/36 分量）

召回

10/10 标注名

幻觉数

0

维度/引用一致性率

100%

几何自洽率

100%

平均调用次数

1.0（无重试，贪心直出即达标）

平均延迟

3.1s/图

唯一未满分项 tri_sides_01：顶点 C 坐标（3.879→5.9 级读数偏差）未精确命中 GT， 但几何自洽校验全部通过（偏差在容差内）——这正是"不把对的说错"的设计。 --baseline 基线对比显示：这批简单合成图上确定性层是安全网（防止漏数/幻觉被当真）， 而非分数助推器；在更复杂的真实题图（模糊/密集标注）上，补漏重试的收益会显现。

🤔 第一次用，先确认这几点

1. 拿视觉模型的 Key（阿里云百炼 / DashScope） 推荐模型 qwen3-vl-flash 来自阿里云百炼。去 dashscope.console.aliyun.com 注册/登录阿里云 → 开通百炼 → 创建「API Key」（SK- 开头）。所有使用方式（CLI / MCP / 插件）都只需要这一个 Key。

2. 三种接入方式，先跑通哪一个？

  • 只想快点看效果 → 用「命令行 CLI」（最直接，一条命令出结果）。

  • 想让 opencode 的 agent 能看图 → 用「opencode 视觉插件」（推荐给开发）。

  • 想在自己写的 Python 脚本里调用 → 用「快速开始（Python API）」。

下面按「CLI → opencode 插件 → DSH 插件」顺序介绍，按需跳到你需要的章节即可。

3. 工作在哪个目录？ 仓库根目录就是 vision_kit 的包根（见 pyproject 的 package-dir）。请在克隆下来的仓库根目录运行命令与放置图片， 这样 python -m vision_kit.* 和 test_figure.png 才能被找到。

快速开始（Python)

💡 推荐视觉模型：qwen3-vl-flash —— 阿里云百炼（DashScope）开箱即用的轻量多模态视觉模型， 对中文数学/几何题图里的数字标注识别稳定，速度与成本兼顾。vision_kit 已针对 OpenAI 兼容协议 做了参数化调用， 直接通过环境变量指定即可，无需改代码。 若你更喜欢智谱的 glm-4v-flash：把 VISION_API_BASE 换成 https://open.bigmodel.cn/api/paas/v4、VISION_MODEL 换成 glm-4v-flash， 并记得把 VISION_MAX_TOKENS 同步改回 1024（glm-4v-flash 上限是 1024，见下方「参数调优」）。 下面示例默认使用 DashScope（阿里云百炼）兼容端点。

# 克隆后，在仓库根目录执行
pip install -e .            # 安装（openai / pillow / mcp）
export VISION_API_KEY=你的Key    # 填你在阿里云百炼创建的 SK- 开头 Key
# 下面两个是可选默认值（官方 DashScope 端点 + qwen3-vl-flash），不设也能用：
export VISION_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1   # 可选
export VISION_MODEL=qwen3-vl-flash                                        # 可选
from vision_kit import VisionClient

client = VisionClient(api_base="https://dashscope.aliyuncs.com/compatible-mode/v1",
                      api_key="你的Key", model="qwen3-vl-flash")
text = client.describe("题目图.png")            # 渲染文本（供 LLM 注入）
data = client.describe_structured("题目图.png") # 结构化 dict

需要先安装吗？

vision_kit 把仓库根目录映射为包根（pyproject.toml 的 package-dir: vision_kit = "."）。 有两种使用方式，按需选一种即可：

  • 推荐（CLI / MCP 最省事）：pip install -e . 安装一次，之后任意目录都能 python -m vision_kit.*。

  • 也可以不安装：把仓库目录加入环境变量 PYTHONPATH 后直接 import vision_kit（DSH 插件的 visionKitDir 就是这么用的）。

两者二选一即可，不必都做。 若既没安装、又没设 PYTHONPATH，python -m vision_kit.cli 会报"找不到模块"。

命令行（供插件 / 脚本调用）

python -m vision_kit.cli 题目图.png --mode describe   # 自然语言描述 / 问答
python -m vision_kit.cli 题目图.png --mode extract    # 结构化识别（JSON）
python -m vision_kit.cli 题目图.png --mode both
python -m vision_kit.cli 统计图.png --mode stats      # 统计图 → 数据表（类别/系列数值）
python -m vision_kit.cli 几何图.png --mode extract --type geometry   # 图型专用提示词模板
python -m vision_kit.cli 几何图.png --mode extract --tikz            # 附带可编译 TikZ 片段
# 或安装后：vision-kit-cli 题目图.png --mode extract

输出单行 JSON：{"ok": true, "mode": "extract", "result": {...}}，失败时 {"ok": false, "error": "..."} 且退出码 1。 凭证读取环境变量 VISION_API_KEY / VISION_API_BASE / VISION_MODEL / VISION_TIMEOUT / VISION_MAX_TOKENS（与 MCP 服务器一致）。

试着跑一下（最快验证）

# 在仓库根目录（这样能找到自带的 test_figure.png）
python -m vision_kit.cli test_figure.png --mode extract

注意：test_figure.png 是本仓库自带图。用全局插件 / 在自己项目里跑时，工作区里没有它， 请换成你自己的图片路径，或先 cd 到仓库根目录再跑。图片路径按当前工作目录解析。

opencode 视觉插件（推荐）

给 coding agent 一双“眼睛”：无需切换多模态模型，任意文本模型也能看图。

提供两个工具

工具

作用

vision_describe

看一张图，返回中文描述，或回答关于图的具体问题（传入 prompt）

vision_extract

结构化识别图中的数字标注：向量 / 矩阵 / 坐标 / 角度，带维度校验与补漏重试

安装

插件是放在插件目录的 JS 文件，opencode 启动时自动加载（无需改配置）：

# 前提：先克隆本仓库，并使用仓库根目录的 .opencode/plugins/vision-kit.js

# 项目级（只在该项目生效）：先创建目标插件目录（若不存在）再复制
mkdir -p <你的项目>/.opencode/plugins
cp .opencode/plugins/vision-kit.js <你的项目>/.opencode/plugins/

# 全局（所有项目生效）：
mkdir -p ~/.config/opencode/plugins
cp .opencode/plugins/vision-kit.js ~/.config/opencode/plugins/

上面的 cp 需要在仓库根目录执行。若只想要插件、不用整个库，直接拷贝那个单文件即可， 插件运行时会调用 python -m vision_kit.cli，所以目标机器仍要能 import vision_kit（见「要不要 pip install」）。

凭证（按优先级）

  1. 环境变量 VISION_API_KEY / VISION_API_BASE / VISION_MODEL / …

  2. opencode 配置 mcp["vision-kit"].env（全局 ~/.config/opencode/opencode.json 或项目 .opencode/opencode.json，即 opencode.example.json 中的写法）

无需重复填 Key：只要你的 opencode 配置里已有 vision-kit MCP，插件自动复用同一组凭证。

到底该在哪儿填 Key？一张表说清（避免到处都填乱）：

你要用

该在哪儿配

说明

opencode 插件

opencode 配置 mcp["vision-kit"].env 的 VISION_API_KEY

插件自动复用，最省事

CLI / MCP 服务器

环境变量 VISION_API_KEY（或 opencode.json env）

运行前 export 或写在 env

DSH 插件

vision.config.json 的 apiKey

见下方 DSH 章节

三处配同一个 Key 即可，不必每处都填；按你实际用的接入方式配对应那一个地方就够。

实现方式

插件不重复实现任何视觉逻辑：调用 python -m vision_kit.cli，完全复用本项目的图片预处理、结构化识别、维度校验、补漏重试与超大图分块。插件本身只负责路径解析（相对路径基于会话目录）、凭证注入与结果格式化。

试一下

opencode run "用 vision_describe 看一下 test_figure.png，告诉我图里有哪些向量"
opencode run "用 vision_extract 提取 test_figure.png 中的结构化数据"

test_figure.png 是本仓库自带的一张向量题示例图，在仓库根目录。 用全局插件 / 在别的工作区跑时，请换成你自己图片的绝对路径。

opencode MCP 服务器

python -m vision_kit.mcp_server   # 或安装后：vision-kit-mcp

通过 opencode.example.json 接入 opencode（DashScope qwen3-vl-flash 示例）。

DeepSeek Harness 视觉插件

与 opencode 版同源的 DSH 固定 Cordis 插件（dsh-plugin/vision-kit.dsh.js）， 给 DSH 的任意文本模型一双“眼睛”：注册 vision_describe / vision_extract 两个模型工具， 通过 python -m vision_kit.cli 复用本项目的全部视觉逻辑。 vision_extract 额外把 几何自洽校验 结果（geo_checks）返回给模型：三角形内角和、向量加法关系、 矩阵乘法维度、负值等，任一不通过会触发采样重试，重试耗尽后逐条展示 ✗ 不通过，让文本 agent 能察觉"读数自相矛盾"而非盲信。

首次配置（必须）

DSH 插件从仓库根的 vision.config.json 读取视觉凭证。出于安全考虑，这个文件不会被项目分发，需要你在自己机器上创建一份：

# 在仓库根目录
cp vision.config.example.json vision.config.json
# 然后编辑 vision.config.json，填入：
#   apiKey      —— 你在阿里云百炼创建的 SK- 开头 Key（必填）
#   python      —— （建议）你的 python.exe 绝对路径
#   visionKitDir—— 本仓库根目录的绝对路径（插件据此定位 cli.py 与 vision.config.json）

  • 模板 vision.config.example.json 不含密钥，可放心参考。

  • ⚠️ vision.config.json 保存的是你的 API Key，参考项目配置即可，不要把它分享/上传。

  • 插件自动定位项目目录：优先读 VISION_KIT_DIR 环境变量，其次由插件文件自身位置推导 （本文件位于 <仓库根>/dsh-plugin/vision-kit.dsh.js，仓库根即上一级目录），再回退到当前工作目录探测。

安装与启用（固定插件，重启后保留）

本插件现在是 DSH 固定插件：作为组合行写进 $DSH_HOME/profiles/web/cordis.patch.yml， 随 DSH Web 部署启动自动挂载、重启后保留，不需要每次 cordis_define 重新定义：

# $DSH_HOME/profiles/web/cordis.patch.yml
- insert:
    - id: vision_kit
      name: 'file:///D:/libs/vision_kit/dsh-plugin/vision-kit.dsh.js'

  • name 必须是 file:// URL 形式：原始 Windows 路径 D:\... 会被 Node ESM loader 当作 d: scheme 拒绝。

  • 插件文件是 CommonJS 模块（module.exports），工具通过 ctx.tools.register(...) 全局注册， 挂载后所有会话立即可用（新开会话生效；已打开的会话可在下次启动后看到）。

  • 等价的手动 overlay 写法见 dsh-plugin/cordis.yml（dsh web --patch 用）。

  • 修改插件代码后需要重启 dsh web（编辑 patch 文件本身可触发热重载）。

路径

image_path 支持相对路径（基于调用方会话工作区）或绝对路径。

样例图的模型说明（重要）

README 各处"试一下"用的 test_figure.png 识别结果，是按默认模型 qwen3-vl-flash（DashScope）标定的。 不同视觉模型对同一张图的抽取可能有细微差异，若你换成 glm 等，结果可能不完全一致，属正常现象。

试一下

用 vision_describe 看一下 test_figure.png，告诉我图里有哪些向量
用 vision_extract 提取 test_figure.png 中的结构化数据

test_figure.png 在本仓库根目录。用全局插件 / 在别的工作区跑时，请换成你自己图片的绝对路径。

环境变量

变量

必填

默认

VISION_API_KEY

是

-

VISION_API_BASE

否

https://dashscope.aliyuncs.com/compatible-mode/v1

VISION_MODEL

否

qwen3-vl-flash

VISION_TIMEOUT

否

60

VISION_MAX_TOKENS

否

8192（qwen3-vl-flash 上限）

VISION_KIT_DIR

否

无。DSH 插件项目目录 + PYTHONPATH；插件优先读它定位项目，未设置则自动探测/按模板引导配置

参数调优建议

环境变量与引擎常量已给出合理默认值，大多数场景无需改动。若你有特定需求，可按下面调整：

关于 max_tokens

  • 默认 8192 是 qwen3-vl-flash 的上限。视觉结构化输出通常是短 JSON（向量/矩阵/说明）， 实际用量往往只有几百到一两千 token —— 所以即使调小到 1024~2048 也极少截断，还能稍微降成本。

  • 若一次要返回很大的矩阵、或图内文字很多，担心被截断，就保留 8192；需要更多才另说。

  • ⚠️ 换模型时务必同步改这个值：推荐默认按 qwen3-vl-flash（上限 8192）， 若改用智谱 glm-4v-flash，其上限 只有 1024，用 8192 会直接报参数超限 —— 记得 VISION_MAX_TOKENS=1024。

针对不同使用倾向

你的诉求

建议调整

说明

更准（容忍慢）

VISION_TIMEOUT 调大，如 120

图片预处理+补漏重试+分块可能较慢，超时太紧会误判失败

更省成本

VISION_MAX_TOKENS 调到 1024~2048

结构化输出普遍够用，可减少付费 token 溢出浪费

图很小/字很密

调大引擎 MIN_DIM（engine.py，默认 1000）

小图自动放大，放大得越足数字越清楚

超大图（会分块）

调小引擎 MAX_TILE_SIDE（默认 1600）

块越小单模型压力越小，但块变多、开销变大

补漏更彻底

调大引擎 MAX_ATTEMPTS（默认 3）

维度/几何校验不通过时重试次数，越多越稳但越慢

环境变量（VISION_*）通过 CLI / MCP / opencode 插件的 env 直接改即可，无需动代码； 引擎常量（MIN_DIM / MAX_TILE_SIDE / MAX_ATTEMPTS 等）在 engine.py 顶部修改后重新调用即可。

开发

pip install -e ".[dev]"
pytest              # 单元测试（tests/）
ruff check .        # 代码质量

# 基准（2.1）：重新生成题图（确定性，无需 API）
python benchmark/generate_images.py           # 主集 + 对抗集 + 困难集
# 跑评测（需要 VISION_API_KEY）：逐图指标 + REPORT 榜单
python benchmark/eval.py --limit 3            # 快速试跑
python benchmark/eval.py                      # 主集全量 → REPORT.md
python benchmark/eval.py --subset adv         # 对抗注入集 → REPORT_ADV.md（校验层防护率）
python benchmark/eval.py --subset hard        # 困难集 → REPORT_HARD.md（扰动下补漏重试价值）
python benchmark/eval.py --baseline           # 额外跑单次直出基线，对比校验层增益
# 回归快照（2.4）：记录/比对真实模型输出基线（需要 VISION_API_KEY）
python benchmark/eval.py --update-snapshots
pytest tests/test_snapshots.py               # 数值级回归比对（离线自动跳过）

项目结构

vision_kit/
├── __init__.py       # 包入口，导出 VisionClient（__version__ = 0.3.0）
├── client.py         # VisionClient：放大预处理 / 结构化 / 分块合并校验 / 定向重试 / 渲染回写 / 内容寻址缓存
├── engine.py         # 识别引擎：提示词、参数化调用、定向重试（失败规则→提示）、超大图分块合并再校验
├── figure.py         # FigureData：图元 DOM（含圆上点/四边形）+ 向量/矩阵解析 + 维度/引用校验 + 几何校验 + 分块合并 + 渲染回写 + TikZ
├── geometry.py       # 几何自洽校验：三角内角和 / 向量加法 / 矩阵维度 / 线段长度 / 三角形不等式 / 勾股 / 圆定理 / 相似 / 平行四边形 / 函数对称 / 负值（纯逻辑）
├── stats.py          # 统计图 → 数据表（4.3）：类别/系列数值 + 长度对齐/百分比求和/非负校验 + 重试
├── prompts.py        # 场景化提示词模板（4.1）：geometry / function / vector / statistics
├── cli.py            # 命令行 JSON 入口（--mode describe|extract|both|render|stats，--type/--tikz/--render）
├── mcp_server.py     # opencode MCP 服务器（stdio；describe_image / structured / stats）
├── benchmark/        # 2.1 基准：合成题图 + 对抗注入集 + 困难集 + ground_truth* + eval.py（--subset/--baseline，产出 REPORT*.md）
├── tests/snapshots/  # 2.4 回归快照基线（真实模型输出，数值级比对）
├── opencode.example.json
├── vision.config.example.json   # DSH 插件配置模板（不含 Key，可直接用）
├── vision.config.json           # 本机视觉凭证（由模板复制后填写，属本地文件，不随项目分发）
├── .gitignore          # 已排除 vision.config.json 等本地文件
├── dsh-plugin/
│   ├── vision-kit.dsh.js       # DeepSeek Harness 固定视觉插件（CommonJS 模块）
│   └── cordis.yml              # 等价 overlay（dsh web --patch 用；固定安装见 $DSH_HOME/profiles/web/cordis.patch.yml）
└── .opencode/
    └── plugins/vision-kit.js   # opencode 视觉插件（见上文）

Available Tools

3 tools
describe_imageA

通用视觉描述：调用视觉模型观察图片并返回中文描述文本。

Args: image_path: 本地图片文件路径（支持 jpg/png/bmp 等，超长图自动分块）。 prompt: 可选的自定义描述要求；缺省使用通用描述提示词。

ParametersJSON Schema
NameRequiredDescriptionDefault
promptNo
image_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries the behavioral disclosure burden. It adds meaningful traits beyond the schema: supported image formats (jpg/png/bmp), automatic chunking of overlong images ('超长图自动分块'), and the default prompt behavior. It does not discuss external API dependencies or failure modes, but the key runtime behavior is disclosed.

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 compact and front-loaded: one purpose sentence followed by a two-line Args section with no filler. Every sentence adds either purpose or parameter semantics.

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 simple two-parameter tool with an output schema, the description covers the essential usage context, formats, and defaults. It is not quite complete because it never positions the tool against its siblings or notes constraints such as network/service requirements, but nothing critical is missing for a straightforward call.

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 description coverage is 0%, so the description fully compensates by documenting both parameters. image_path is explained as a local path with supported formats and auto-chunking behavior, and prompt is explained as optional with a clear default. This goes well beyond the JSON schema's bare title/type declarations.

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

Purpose4/5

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

The description clearly states a specific verb and resource: it calls a vision model to observe an image and return a Chinese description ('调用视觉模型观察图片并返回中文描述文本'). The output type is clear, but it does not explicitly contrast itself with the sibling tools describe_image_structured or describe_image_stats, so it stops short of full differentiation.

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 clearly labels itself as the generic visual description tool ('通用视觉描述') and explains the default prompt behavior, giving an agent enough context to know when the general-purpose description is appropriate. However, it does not explicitly name sibling alternatives or state exclusions, so it does not earn a 5.

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

describe_image_statsA

统计图 → 数据表：提取柱状/折线/饼图中的类别与数值序列（4.3）。

Args: image_path: 本地图片文件路径。

Returns: dict，包含 type（图表类型）、categories（类别）、series（系列数值）、 note（说明）与 checks（自洽校验：长度对齐 / 百分比求和 / 非负）。 识别失败时返回 {"error": "..."}。

ParametersJSON Schema
NameRequiredDescriptionDefault
image_pathYes

TDQS

A4.1/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It documents the return contract (type, categories, series, note, checks), the self-consistency validation behaviors (length alignment, percentage sum, non-negativity), and the failure return format. It does not explicitly say the operation is side-effect-free, but as a local image extractor the return/error contract is reasonably 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?

The description is dense and front-loaded, with a clear purpose line followed by Args and Returns sections. The only minor flaw is the unexplained '（4.3）' version-like marker, which adds a small amount of noise but does not significantly hurt scannability.

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 single-parameter tool with no output schema, the description covers the input semantics, the output dict shape, the validation checks, and the error behavior. It lacks explicit examples and detailed value types for categories/series/checks, but an agent has enough information to select and invoke the tool correctly.

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 0%, and the description compensates by defining image_path as '本地图片文件路径' (local image file path). This is sufficient for the single required parameter, though it could add detail about accepted formats or path resolution.

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 states a specific verb ('提取' / extract) and a specific resource ('柱状/折线/饼图中的类别与数值序列' — categories and numeric series from bar/line/pie charts). The '统计图 → 数据表' framing clearly distinguishes this tool from the more generic sibling tools describe_image and describe_image_structured.

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 chart-to-data-table purpose implies when to use it, but the description never explicitly says 'use this when the image is a statistical chart' or 'use describe_image_structured instead for general structured image description.' No alternatives or exclusions are named, so usage guidance is implied rather than stated.

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

describe_image_structuredA

结构化识别：提取图片中带数字的标注（向量/矩阵/坐标/角度/未知量）。

Args: image_path: 本地图片文件路径。

Returns: dict，包含 type（图形类型）、vectors（向量）、matrices（矩阵）、 note（说明）与 text（渲染文本）。识别失败时返回 {"error": "..."}（避免返回 None 与声明类型 dict 不符）。

ParametersJSON Schema
NameRequiredDescriptionDefault
image_pathYes

TDQS

A3.9/5.0
Behavior4/5

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

No annotations were provided, so the description must carry the behavioral disclosure burden. It does so by stating that recognition failure returns '{"error": "..."}' instead of None, which clarifies the failure contract. It also reads as a read-only extraction operation ('extract') and documents the output shape, giving the agent useful information beyond the input schema.

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 efficiently organized: a one-sentence purpose, an Args section for the parameter, and a Returns section with error handling. It avoids fluff, repeats no schema information, and each line earns its place.

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 one-parameter tool with no annotations and no output schema, the description covers the required input, the expected return keys, and the failure mode, which is enough for basic invocation. It would be more complete if it gave interaction between 'type', 'note', and 'text' or guidance on which images are out of scope, but nothing critical is missing.

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?

The input schema provides only a bare string property named 'image_path', while the description adds that it must be a local image file path ('本地图片文件路径'). That is genuine semantic added value over 'string' and enough to resolve the one required parameter, although it does not discuss supported formats, relative vs absolute paths, or preprocessing behavior.

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

Purpose4/5

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

The description clearly identifies the action ('extract') and resource ('images with numeric annotations including vectors, matrices, coordinates, angles, unknowns'), which makes the tool's purpose specific and distinct from plain image captioning. It also enumerates the expected return keys, reinforcing the structured-recognition scope. It stops short of a 5 because it never explicitly contrasts itself with the sibling tools 'describe_image' and 'describe_image_stats'.

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?

'结构化识别' and the list of extracted quantities imply the intended use: when an agent needs numerical/structured details from an image rather than general description or statistics. However, the description does not explicitly say when to choose this tool over the named siblings or when not to use it, so the guidance is mostly implied rather than stated.

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. Dates show when Glama detected each change.

  1. 3 tool updatesv0.3.0
    • First observeddescribe_image
    • First observeddescribe_image_stats
    • First observeddescribe_image_structured
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation4/5

describe_image is a generic catch-all, while the other two tools target specific image types with distinct output schemas. The overlap with the generic tool is acceptable because the specialized descriptions clearly define when to use them.

Naming Consistency5/5

All tools share the describe_image_ prefix followed by a clear modifier: structured and stats. This creates a predictable and consistent naming convention across the entire server.

Tool Count5/5

Three tools is within the well-scoped range, and each tool serves a distinct, meaningful vision task without redundancy. The small count feels deliberate rather than incomplete.

Completeness4/5

The set covers generic visual description, structured diagram extraction, and statistical chart parsing, which are the main advertised capabilities. Some advanced vision tasks like object detection or OCR are absent, but the generic describe_image tool can work around many gaps via custom prompts.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Seom-ingit/vision_kit'

If you have feedback or need assistance with the MCP directory API, please join our Discord server