选中任意元素，就地修改。 文字、图片、形状、线段、图标、图表、表格、时间线和二维码放在同一块画布上；多页作品的每一页可以设不同尺寸。
文字：选中一段单独加粗、标色、高亮或加下划线；16 种花字一键套用（霓虹、描边、立体、标签底色……）；自己的字体文件（TTF / OTF / WOFF / WOFF2）可以导入，画布和导出都按它画。
图片：独立图片进入裁剪后，可以在原画框里移动图片、拖动八个黑柄，或按比例调整画框；还能加圆角、相框和滤镜。部署服务端后，图片抽屉里的在线图库可以直接搜可商用的图片。
素材：97 个可搜索的线性图标，48 个手绘线条、贴纸和标签；图表有柱状、环形、折线和雷达，数据可以从表格里整列粘贴。
风格：一键给整套卡片换配色或字体组合；改一个颜色或字体时点「全部替换」，整套里同样的颜色和字体一起换掉。
图层：改名、排序、编组、隐藏、锁定。
导出与分享：PNG、JPG、PDF，可以只导当前页，也可以打包成 ZIP、合成一个 PDF、拼成一张长图，或切成朋友圈九宫格。部署服务端后还能生成分享链接，手机扫码就能看，长按存图。
Related MCP server: StoreCraft Studio
一篇长文，按卡片尺寸自动分页。 把 Markdown 粘到左边，右边按小红书、微博或推特的尺寸实时分页；--- 手动分页，标题不会单独落在页底。图片粘贴后可以在预览里直接调宽度。
九套长文版式：专栏、备忘录、信笺、夜读、极光、文档、宣纸、瑞士、手账。每套有自己的页眉、页码、标题层级、引文、列表、待办、代码和表格样式，正文一个字不动就能换。
88 套模板，都在仓库里维护。
Markdown 长文版式 9 套。
三页套图 自由画布有八套：编辑部、清单、信号、夜航、粗野、蓝图，和 16:9 的演示套图聚光、答辩。封面、内页、结尾各一页；用 MCP 生成整套卡片时，会按每页的内容换成观点页、清单页、数据页或收尾页。
单页模板 71 张，覆盖 8 种尺寸：小红书 3:4、竖版海报 9:16、方图 1:1、横版 16:9、公众号首图 2.35:1、A4 竖版和横版、朋友圈九宫格。从封面、海报、菜单价目、证书、简历和通知，到节日节气和邀请贺卡。
模板中心按名称、标签、用途和风格搜索，再按尺寸、风格、颜色和收藏筛选；每套模板按自己的比例排开，点开先看每一页和相似模板。在编辑器里，模板也能一页一页加进正在做的作品。做了一套好看的版式，可以按贡献模板提交 Pull Request，合并后所有人都能用。
AI 客户端，直接出整套卡片。 stdio MCP 服务器 dingcard-mcp 发布在 npm 上，提供 22 个工具，也登记在 MCP 官方注册表，名字是 io.github.lottshin/dingcard。文档校验、编辑和渲染跟编辑器共用同一套代码；工具之间传 documentId，图片可以直接写本机路径。在 MCP 客户端的配置里加上：
{
"mcpServers": {
"dingcard": { "command": "npx", "args": ["-y", "dingcard-mcp"] }
}
}需要 Node.js 22 以上和本机安装的 Google Chrome（渲染和检查用）。
工具 | 做什么 |
| 列出模板的尺寸、用途、风格，以及能放多少内容 |
| 按内容生成整套卡片，模板的示例文字全部换掉 |
| 按导出的样子检查文字被裁、叠住、对比度低、残留示例文字和大片留白，放不下的字自动缩小 |
| 无头渲染成逐页 PNG、JPG，一个 PDF、一张长图或九宫格切图 |
| 在叮卡编辑器里打开，由人接着改 |
另外还有按大纲生成整套卡片、生成单张海报、把 HTML 转成可编辑的设计、加入模板页、放装饰素材、搜索和导入在线图库的图片、生成分享链接、读写服务端作品和渲染 Markdown 长文等工具。完整清单、客户端接入配置和安全边界见 MCP 自动化接口。AI 生成的 .json 文档也可以拖进「我的项目」，存成项目后在编辑器里打开。
由 MCP 绘制，没有用一张图片：54 个形状、46 条线段、5 段文字和 9 组多段渐变。月晕是同心椭圆加模糊，山脊是远淡近浓的三层剪影，湖面的波纹是一条条线段（右页的红点是它们的控点）。整份文档在 docs/assets/yamatsuki-poster.json，拖进「我的项目」就能拆开重编。
打开在线 Demo 就能用，不需要账号。作品自动保存在当前浏览器里，重要作品记得导出。
想要一份自己的在线地址，可以一键部署到 Vercel。不需要环境变量，作品同样保存在访问者的浏览器里。
需要真实账号、跨设备同步、服务端图片和分享链接时，用 Fastify + SQLite 后端部署完整应用。预构建镜像支持 linux/amd64 和 linux/arm64：
docker pull ghcr.io/lottshin/dingcard:0.60.0.env.example 中的 DINGCARD_VERSION=0.60.0 会固定使用上面的镜像。下面的流程适用于已经安装 Git、Docker Engine、Docker Compose 和 OpenSSL 的 Linux 服务器：
git clone https://github.com/lottshin/DingCard.git
cd DingCard
cp .env.example .env
JWT_SECRET="$(openssl rand -hex 32)"
sed -i "s/^JWT_SECRET=.*/JWT_SECRET=${JWT_SECRET}/" .env
unset JWT_SECRET
docker compose pull
docker compose up -d --no-build
curl -f http://127.0.0.1:8080/api/health健康检查返回 {"ok":true} 后，通过 http://服务器地址:8080 打开叮卡。域名、HTTPS、备份、升级、在线图库和源码构建见部署指南。
在线版和本地运行默认用本地模式（LocalStore），账号和作品存在当前浏览器里，清理浏览器数据会一起删掉。部署了服务端就是服务器模式（RemoteStore），账号和作品存在服务器上，能跨设备同步。两边是独立的数据源，切换模式不会迁移已有的账号、作品或图片。
需要 Git、Node.js 22+ 和 npm，不需要后端：
git clone https://github.com/lottshin/DingCard.git
cd DingCard
npm ci
npm run dev测试命令、服务器模式联调和数据存储的细节见开发指南。
React、TypeScript、Vite 写成，后端是 Fastify + SQLite。以 MIT 许可开源。
把装饰素材放到一页上（一次可放多个，按顺序叠放；list_assets 的 decorations 查 id）：每项给 decoration、x、y（盒子左上角的页面坐标）、width（不给按页面短边的默认比例），高度按装饰的宽高比算。color（#RRGGBB）换掉装饰本来的主色（手绘线条和贴纸换整体颜色，标签换底色，字色自动取黑或白）；text 换标签上的字；rotation 旋转（度）；below 填同页一个顶层节点的 id 或图层名，装饰就放在它下面一层（荧光笔、胶带、色块垫在文字下面时用），不给则放在最上层。用 documentId 时就地更新这份文档，返回每个装饰的 nodeId、path 和盒子；之后可以用 apply_actions 改，用 check_document 检查有没有压住文字。
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | 要放的装饰，按顺序叠放 | |
| slideId | No | 放在哪一页，默认文档当前页（activeSlideId） | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does so richly: stacking order for multiple items, default width from the page's short edge, height derived from aspect ratio, per-type color semantics (lines/stickers recolor, labels recolor background, text auto black/white), layering relative to a top-level node, in-place update via documentId, and the return payload (nodeId、path、盒子).
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?
Front-loaded with the action and dense with actionable detail; every clause carries information. It is a single semicolon-chained sentence, which makes it harder to scan than it could be, but there is essentially no filler.
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 6-parameter mutation tool with no annotations and no output schema, the description covers what is created, defaults, layering, the document-passing options, return fields, and the follow-up tools. Nothing an agent needs to invoke it correctly is missing.
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 already 100%, but the description still adds real meaning beyond it — how color behaves per decoration type, that text only affects labels, what `below` means in z-order terms, and the default width/height derivation. This is value on top of the schema, not restatement.
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 a specific verb+resource (把装饰素材放到一页上), states batch scope (一次可放多个，按顺序叠放), and tells where decoration ids come from (list_assets 的 decorations 查 id). An agent can distinguish this from apply_actions or add_template_pages without opening any schema.
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 gives concrete conditional guidance: use `below` for highlighters/tape/color blocks that must sit under text, and it states the follow-up path (改 with apply_actions, 检查 with check_document). It does not say when NOT to use this tool versus a sibling, so it falls just short of explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把模板的页面加进一份自由画布文档，和编辑器模板面板里点一页一样：套图模板可以只加某几页（再来一张内页、换个结尾页），单页海报加进来就是新的一页。页面保留模板自己的尺寸和示例文字，之后用 inspect_document 找到图层、apply_actions 改字，check_document 会把没改的示例文字报出来。要直接按内容填好：套图的页用 create_document_from_content 每页的 templateId，海报用 create_poster_from_content 的 documentId。返回加进来的页（slideId、名称、在文档里是第几页），默认附上这些页的缩略图。
| Name | Required | Description | Default |
|---|---|---|---|
| pages | No | 加模板的第几页，从 1 起（套图是 1 封面、2 内页、3 结尾），可以重复；不给就加全部 | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| previews | No | 是否附上加进来的页的缩略图，默认 true | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| templateId | Yes | list_templates 返回的自由画布模板 id | |
| afterSlideId | No | 加在这一页后面；不给就加在最后 | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| replaceSlideId | No | 换掉这一页（比如一张空白页），不能和 afterSlideId 同时给 | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that pages keep the template's own size and sample text, that check_document will flag unedited placeholders, and what the return payload contains plus the default thumbnail behavior. It does not state whether replaceSlideId is destructive/irreversible or what happens to existing content when a slide is swapped.
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 core action is front-loaded in the first clause, and each subsequent sentence adds workflow, alternatives, or return-shape value. It is dense and long for a single description, with some overlapping coverage of the two creation alternatives, but little is pure filler.
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 9-parameter mutation tool with no annotations and no output schema, the description covers the return values (slideId, name, page position), the thumbnail default, and the editing workflow. The main residual gap is the absence of any warning about replaceSlideId replacing existing content, which matters for safe invocation.
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 schema already explains pages, templateId, previews, afterSlideId/replaceSlideId mutual exclusion, and document alternatives. The description adds the useful framing that 'pages' maps to real template structure and that this is the manual counterpart to the content-filling tools, but adds no syntax or format detail beyond the schema.
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?
States a specific verb and resource ('把模板的页面加进一份自由画布文档') and immediately analogizes to clicking a page in the editor template panel, covering both multi-page and single-page poster cases. It names the sibling tools that serve adjacent needs, so an agent can distinguish it without opening a schema.
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?
Explicit alternatives with conditions: use create_document_from_content with per-page templateId for content-filled multi-page docs, and create_poster_from_content's documentId for posters. It also lays out the correct follow-up workflow (inspect_document → apply_actions → check_document) for editing sample text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
对文档应用一串编辑动作（与编辑器 UI 同一归约器，语义完全一致），返回每个动作是否生效（changes）和没生效的原因（reasons，与 changes 一一对应：没改动时是 null，被拒时写清哪个键、哪条规则）。用 documentId 时就地更新这份文档（version 加一），传 document / documentPath 时另存为一份新文档并返回它的 documentId；动作里图片 src 写成本机文件路径的会读进来嵌入。常用：node/insert-children（插入节点）、node/update-content（改字/改数据元素内容）、node/update-style（改样式）、node/update-geometry（改位置尺寸）、slide/*（页的增删换序）、document/find-replace（整套查找替换）、document/restyle（整套换配色字体）。每个动作的完整写法见 get_guide("actions")。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。
| Name | Required | Description | Default |
|---|---|---|---|
| actions | Yes | FreeformAction 数组 | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does so: it discloses the return contract (changes array plus one-to-one reasons, null when nothing changed, which key/rule caused rejection), the two persistence modes and version increment, and the side effect of embedding local image files. That is unusually complete for a mutation tool with zero annotation coverage.
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?
Core behavior and the two save modes are front-loaded, then the action catalog and guide pointers. The common-action enumeration is long but functional. Minor compression opportunity in the reasons explanation, which is slightly verbose.
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 complex mutation tool with a freeform actions array and no output schema, the description supplies the return shape, persistence semantics, and pointers to the authoritative action and document-model guides. Nothing essential to a correct first call is missing.
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, but the description adds real meaning the schema does not: documentId means in-place update versus document/documentPath meaning save-as-new, and that image src as a local path gets embedded. includeDocument is left to the schema, which is acceptable.
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?
States a specific verb+resource: apply a batch of edit actions to a document, evaluated by the same reducer used by the editor UI. The mutation/scoping story is explicit enough that an agent can distinguish it from get_document, validate_document, or render_document without opening any schema.
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?
Gives clear mode-selection guidance: documentId edits in place (version bumps), document/documentPath writes a new document and returns its documentId. It also routes the agent to get_guide("actions"), get_guide("document-model"), and the dingcard://schema/freeform resource for syntax. No explicit 'do not use this when…' exclusion against a named sibling, so it stops just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
检查自由画布文档排出来的样子：在与导出相同的页面里排版后，逐页列出读者会注意到的问题——文字放不下、叠住、被挡住或跑出页面，对比度太低，还留着示例文字，图片没加载出来，图形、二维码、表格、图表画坏了，对齐差几 px，标题和正文拉不开层级，页面上一大片空白，该放图片的色块空着。每条带 kind、page、slideId、node（图层名）、path（apply_actions 用的节点路径）和改法，每种 kind 是什么意思见 get_guide("check")。fix: true 时把放不下的文字缩到能放下的字号、把差几 px 的对齐吸齐，并保存（用 documentId 时就地更新，返回 documentId 和 version），附改了哪些（fixed 是缩过的字号，snapped 是挪过的位置）和剩下的问题。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | 把放不下的文字缩到能放下的字号、把差几 px 的对齐吸齐（改动保存回这份文档，返回 documentId 和 version） | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does well: it discloses the returned issue shape (kind, page, slideId, node, path), the exact remediation fix:true performs (shrink overflow text, snap near-aligned elements), that changes are persisted in place, and the returned documentId/version plus fixed/snapped details. It stops short of stating whether the check itself is read-only without fix, or any permission/rate context.
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?
Purpose and the issue taxonomy are front-loaded, and the fix/return behavior follows logically. The long enumeration of defect kinds is dense but each item contributes to recognition; it is slightly overlong for a single paragraph but not padded.
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?
No output schema and no annotations, yet the description explains both the return shape and the fix-path return values, which is what an agent needs. The only real gap is the absence of guidance distinguishing this from validate_document/inspect_document/render_document.
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 already 100%, so baseline is 3, but the description adds real meaning: fix's mutation-and-save behavior, in-place update via documentId returning documentId/version, and the fixed/snapped result semantics. The document/documentPath alternative sourcing is covered in schema but the fix consequences are not.
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?
States a specific verb (check) and resource (freeform canvas document layout) and enumerates the exact defect classes it detects, so the agent knows precisely what comes back. It does not, however, distinguish itself from near-name siblings like validate_document, inspect_document, or render_document, which an agent would need to differentiate.
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?
Usage is implied by the description (use it to find layout problems on a rendered document, set fix:true to repair), and it offers documentId/document/documentPath as input alternatives. But there is no explicit when-to-use-this-vs-validate_document/inspect_document routing, and no stated preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按结构化内容生成一整套自由画布卡片（v44）：封面 + 每个 page 一页 + 可选结尾页，风格沿用所选模板。适合已经整理好标题、正文、要点的内容；每页还能配一种数据元素（chart / table / timeline / progress）。content 的完整写法（页面字段、版式选择、数据元素、生成规则）见 get_guide("deck-content")。生成后建议先 check_document，再 render_document 看缩略图。
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| templateId | Yes | list_templates 返回的自由画布模板 id，如 "editorial-freeform" | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses the versioned nature (v44) and that only documentId and version are returned unless includeDocument is set, which is useful. But it says nothing about permissions, whether an existing document is created new, or rate/limit behavior for a mutation tool.
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?
Front-loads what gets generated, then the suitability condition, then the guide pointer and the suggested verification flow. Dense but each sentence carries information; only the version tag (v44) is arguably noise.
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 deeply nested, 3-parameter generator with no output schema, the description covers the output contract (documentId/version), the follow-up validation path, and where the complex content grammar is documented. Only behavioral details of the write itself are missing.
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?
Adds meaning beyond the 67%-covered schema: content's full authoring spec lives in get_guide("deck-content"), and each page may carry one data element (chart/table/timeline/progress) placed in the whitespace left by text — a constraint not obvious from the schema. templateId is tied to list_templates output, and the default return shape is explained.
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?
States a specific verb and resource: generates a full set of freeform canvas cards (cover + one page per page + optional ending page) using the chosen template's style. It also scopes the input as already-organized title/body/points content, which separates it from outline-driven siblings, though it never names create_document_from_outline or create_document_from_template explicitly.
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?
Gives clear context — use when content is already structured — and prescribes a follow-up workflow (check_document, then render_document), plus routes content-format questions to get_guide("deck-content"). No explicit when-not or sibling comparison, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把你写的 HTML/CSS 网页转成在叮卡里能逐个修改的自由画布文档（v44）。适合模板排不出来的版式：直接用网页写法排版，叮卡在浏览器里排好后，把每个色块、文字、图片和 SVG 图形读成形状、文字框、图片和图形节点，位置、字号、颜色、圆角、阴影、渐变等全部照网页来，层叠顺序按 CSS（含 z-index）。返回 documentId、每页 id 和尺寸、notes（哪里没转过来），默认附缩略图。之后 check_document 检查、apply_actions 修改、render_document 出图、open_in_editor 交给人。HTML 怎么写（section 分页、内置字体、图片、svg、表格、data-name）见 get_guide("html-import")。
| Name | Required | Description | Default |
|---|---|---|---|
| html | No | 网页源码（可以只写 <style> 和若干 <section>） | |
| width | No | 没写尺寸的页面的宽度，也是 100vw，默认 1080 | |
| height | No | 没写尺寸的页面的高度，也是 100vh，默认 1440 | |
| htmlPath | No | 网页文件路径，可替代 html；里面的相对路径按这个文件所在的目录找 | |
| previews | No | 是否附上缩略图，默认 true | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it explains what properties are preserved (position, font size, color, radius, shadow, gradient, stacking order) and flags the 'notes' field reporting what failed to convert — valuable behavioral context. It still doesn't state permissions or size/rate limits, keeping it below a 5.
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?
Front-loads the core purpose, then conversion mechanics, then return values and workflow. Dense but every sentence conveys a distinct fact; slightly long but no clear filler to cut.
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?
Even without an output schema, it describes the return payload (documentId, per-page ids and sizes, notes, optional thumbnail) and the follow-up tool chain, plus a guide reference for HTML authoring. An agent has everything needed to call and act on 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?
Schema description coverage is 100%, so all six parameters (html, width, height, htmlPath, previews, includeDocument) are already documented in the schema. The description adds only scattered hints (default thumbnail) without new syntax or format guidance, so baseline 3 applies.
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?
States a specific verb+resource: converts HTML/CSS web pages into an editable freeform canvas document (v44). The 'template can't do it' framing and detailed conversion mechanics (shapes, text boxes, images, SVG nodes, CSS z-index stacking) clearly differentiate it from sibling creators like create_document_from_template and create_document_from_content.
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?
Gives a clear condition for use ('适合模板排不出来的版式'), names the downstream workflow (check_document → apply_actions → render_document → open_in_editor), and points to get_guide("html-import") for HTML authoring details. It does not explicitly name the alternative sibling to use when a template does fit, so it stops just short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按 Markdown 大纲生成一整套自由画布卡片（v44）：封面 + 每个 "## 小节" 一页 + 可选结尾页，风格沿用所选模板；小节里的 Markdown 表格也变成这一页的表格元素。大纲的完整语法（小节、要点、引文、表格、结尾页）见 get_guide("outline")。生成后建议先 check_document，再 render_document 看缩略图。
| Name | Required | Description | Default |
|---|---|---|---|
| outline | Yes | Markdown 大纲：# 总标题 + 若干 ## 小节（小节下正文行填入该页正文） | |
| templateId | Yes | list_templates 返回的自由画布模板 id，如 "editorial-freeform" | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It usefully discloses that Markdown tables become table elements on the page, that styling follows the chosen template, and that only documentId+version are returned by default. It never states that this is a write operation with persistent side effects, nor any permission or quota constraints — a notable gap for an unannotated mutation tool.
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?
One dense paragraph that front-loads what gets generated and follows with the syntax pointer and verification workflow. Every clause does work, though the parenthetical version tag and nested quoting make it slightly heavier than necessary.
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 no output schema and only three well-documented parameters, the description covers generation semantics, the syntax reference, and a validation path. The main missing piece is explicit disclosure of mutation side effects, which no annotation supplies.
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 context for outline (section/table/ending-page semantics) and template selection, but the concrete semantics of includeDocument and the expected id format come from the schema.
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?
States a specific verb+resource: generates a full set of freeform canvas cards from a Markdown outline, with the exact page mapping (cover + one page per '##' section + optional ending page). That page-structure detail distinguishes it from content-, HTML-, and template-based siblings without needing to name them.
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?
Gives clear workflow: consult get_guide("outline") for the full syntax, then check_document, then render_document for thumbnails. It doesn't explicitly exclude the content/HTML/template alternatives, so the when-not-to-use case is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按模板 id 实例化一份完整的可编辑文档：自由画布模板保存在服务端，返回 documentId（之后传给 inspect_document / apply_actions / check_document / render_document 等）和各页 id、名称；Markdown 模板返回 { source, platformId, themeId, fontFamily, radius, profile, images? } 信封（可用 render_markdown 无头渲染）。
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | list_templates 返回的模板 id，如 "editorial-freeform" | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does real work: it discloses that freeform templates are stored server-side and return a documentId plus per-page ids/names, while Markdown templates return a render envelope with images and can be headlessly rendered via render_markdown. It omits side effects such as permissions, quota, or whether the new document is shared by default.
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 dense sentence that front-loads the core action and then branches into the two return shapes; every clause carries information. It is packed to the edge of readability but has no filler.
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?
No output schema exists, and the description compensates by spelling out the two distinct return payloads and which downstream tool consumes each, so an agent knows what it will get back in either case. For a 2-parameter creation tool this is essentially everything needed to call it 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%, so both templateId and includeDocument are already documented in the schema, and the description adds only the template-source hint already present in the schema text. It never mentions includeDocument or what its default suppression of the full JSON means in practice, so it adds little beyond structured fields.
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?
States a specific verb and resource: 'instantiate a complete editable document from a template id', and immediately splits the behavior by template family (freeform vs Markdown). It does not compare itself to create_document_from_content or create_document_from_html, so an agent must infer why it would pick a template over raw content.
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?
Implied usage is clear: you need a templateId obtained from list_templates, and the output feeds inspect_document / apply_actions / check_document / render_document. However, there is no explicit when-to-use-vs-alternatives statement, so the boundary with the other create_* siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按内容生成一张海报（单页模板：小红书封面、菜单、价目表、证书、九宫格、课程表、各种海报、请柬、贺卡、封面、宣传单、数据盘点、对比表、成长记录等），尺寸跟模板走。模板里的示例文字全部换成内容，没给的连同它的底板、按钮一起删掉。不同模板吃不同的字段（菜单的 details、课程表的 table、数据盘点的 chart、证书的 recipient），content 每个字段的写法和放不下时怎么排见 get_guide("poster-content")；summary.moved / unplaced / shrunk 说明文字放到了哪里、缩了多少。给 documentId 时海报加成那份文档的一页。
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 给了就把海报加成这份文档的一页（就地更新，海报保留自己的尺寸）；documentId、document、documentPath 都不给就新建一份文档 | |
| templateId | Yes | list_templates 里 kind 为 poster 的模板 id，如 "talk-poster-freeform" | |
| afterSlideId | No | 加进已有文档时放在这一页后面；不给就加在最后 | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, yet the description carries the full behavioral load: template placeholder text is replaced, unfilled fields are removed along with their backing plate/button, the poster keeps its own size when inserted into a document, and the summary.moved/unplaced/shrunk fields report where text landed and how much it shrank. That is unusually rich disclosure of mutation and layout-fitting behavior.
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?
Front-loaded with the core action and scoping rule, and every sentence conveys something actionable. The long parenthetical template enumeration and stacked clauses (deletion rule, field mapping, summary fields, documentId) make it dense and slightly run-on.
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 tool with a nested 9-field content object, no output schema, and no annotations, the description covers placement, deletion of unfilled slots, per-template field needs, and return summary semantics. It leaves open what happens on template/field mismatch or invalid templateId, a minor 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?
Schema description coverage is already 86%, and the description adds meaning beyond it by mapping template families to the fields they consume (菜单→details, 课程表→table, 数据盘点→chart, 证书→recipient) and by explaining the precedence among documentId, document, and documentPath. It defers per-field syntax to get_guide, which is acceptable but slightly indirect.
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?
States a specific verb and artifact (generate a poster from content) plus a concrete constraint: it is a single-page template render where size follows the template, with the template categories enumerated (小红书封面, 菜单, 价目表, 证书, 课程表...). This clearly separates it from create_document_from_template and create_document_from_html.
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?
Gives real routing: templateId must come from list_templates with kind=poster, content field syntax is documented in get_guide("poster-content"), and documentId/document/documentPath/neither each select a different target document. It does not explicitly say when to prefer a sibling tool such as create_document_from_template instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
取回一份文档的完整 JSON：给 path 时写成 JSON 文件（目录不存在会创建）并返回路径，不给时直接返回文档。写成文件的文档可以拖进叮卡「我的项目」，或之后用 documentPath 传回来。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | 写到这个 .json 文件，而不是直接返回文档 | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose the non-obvious side effect that a missing directory will be created and that return value differs by mode. It omits error behavior (e.g., a bogus documentId/documentPath) and any permission or payload-size constraints, which keeps it short of full 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?
One compact sentence front-loads the core action and then branches into the two modes, with the payoff of writing a file stated last. It is dense but every clause carries information; a small readability cost from packing all four params' concepts into one run-on sentence.
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?
There is no output schema and no annotations, and the description compensates by describing both possible return values and the filesystem side effect. The remaining gap is that all four parameters are optional, yet the description never states what happens if none of document/documentId/documentPath is supplied.
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 still earns above baseline by explaining that `path` switches the tool into file-writing mode and that the resulting file path can be fed back through `documentPath`. It adds the directory-auto-creation detail not present in the schema, but says nothing about `document` vs `documentId` precedence.
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 verb and resource: "取回一份文档的完整 JSON" (retrieve a document's complete JSON), and it makes the dual-mode behavior explicit (write to file when path is given, return directly otherwise). It does not name or differentiate against near-siblings like inspect_document, check_document, or render_document, so an agent must infer the distinction from the word "完整" (complete).
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 gives a useful selection rule between the two modes of this tool (path vs no path) and explains the downstream use case for the file output (drag into 「我的项目」, or pass back via documentPath). However, it never says when to choose this over inspect_document/check_document or what to do when no identifier is supplied, so usage against alternatives is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按主题读一份使用指南：文档怎么写、每个动作怎么发、content / outline / 海报内容怎么填、HTML 怎么写、模板字段和检查项是什么意思、渲染导出有哪些方式。工具说明里只写了做什么；要动手写参数之前，先来这里读对应主题的完整写法。section 给主题 id（不给就列出全部主题 id 和标题）：document-model 文档模型、actions 动作清单、deck-content 套图内容、outline Markdown 大纲、poster-content 海报内容、html-import 网页转文档、templates 模板清单、check 检查项、render-export 渲染与导出。
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | 主题 id，如 "actions"；不给就列出全部主题 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, and it does disclose the two return modes: with a section it returns that topic's full write-up, without one it returns all topic ids and titles. The read-only nature is implied by "读" and by the absence of any mutation language. It does not explicitly promise no side effects or describe output size, which keeps it at 4.
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 purpose and the when-to-use rule come first, followed by the topic enumeration; every clause maps to a real section id or a real usage rule. The enumeration is long but each item is load-bearing, so nothing is padding. Slightly dense in a single paragraph.
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 one-parameter, no-output-schema lookup tool this is complete: it explains what the tool returns in both modes, why it exists relative to sibling tool descriptions, and what each section id covers. An agent has everything needed to call it correctly on the first attempt.
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% and the enum already lists the nine ids, but the description goes further by glossing each id in Chinese (document-model 文档模型, actions 动作清单, deck-content 套图内容, etc.), which genuinely helps an agent pick the right topic. The omit-behavior is also restated in prose.
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?
It states a specific verb and resource ("按主题读一份使用指南") and enumerates exactly what knowledge lives in the guide: document model, actions, content fields, HTML, templates, checks, render/export. Among siblings like apply_actions or render_document, an agent can immediately tell this is the read-only documentation lookup tool rather than an execution 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?
It gives an explicit trigger: "要动手写参数之前，先来这里读对应主题的完整写法" — read this before composing parameters, because sibling tool descriptions only say what they do. It also states the fallback behavior (omit section to list all topics). It stops short of naming when not to use it, so 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把 search_images 选中的一张照片通过部署的服务端转存到账号的图片库里，得到稳定的原图地址（比缩略图清晰，也不会因为图库改链接而失效）。返回的 url 直接填进图片字段。需要 DINGCARD_SERVER_URL（和账号）；没配置时不用转存，直接用 search_images 结果里的 url。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | search_images 结果里这一张的 id | |
| source | Yes | search_images 结果里的图库源 id（如 pixabay / openverse） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load, and it does disclose the key traits: the transfer happens server-side via a deployed service, it needs DINGCARD_SERVER_URL and an account, and it produces a stable original-resolution URL rather than a thumbnail. It does not address side effects such as duplicate imports or idempotency when the same photo is imported twice.
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?
Front-loaded with the action and its benefit, then the prerequisite and fallback. It is a single dense paragraph with parenthetical asides; every clause contributes, though it could be split for easier scanning.
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 two-parameter tool with no output schema and no annotations, the description covers what is returned (the url to place directly into the image field), the prerequisites, and the fallback path. Nothing an agent needs to invoke it correctly is missing.
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%, and both parameter descriptions already say the values come from search_images results. The description reinforces this ('search_images 选中的一张照片') but adds no format or constraint detail beyond what the schema states, so the baseline 3 applies.
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 verb and resource ('转存到账号的图片库' – transfer a photo into the account's image library) and ties it to a concrete workflow starting point (a photo selected via search_images). It also explains the payoff (a stable original-image URL), which lets an agent distinguish it from the sibling search_images without opening either schema.
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 gives both the when and the when-not: use it after selecting a result from search_images, and skip it entirely if DINGCARD_SERVER_URL is not configured, in which case the url from search_images should be used directly. The prerequisite (DINGCARD_SERVER_URL plus account) is stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
检查文档结构：页面摘要（尺寸/背景/节点数）与递归节点树（id、name、type、几何、文本摘要；内置图标标出 icon id，装饰素材标出 decoration id，组成装饰的组也标在组上），以及整套卡片的 style：用到的颜色（按占的面积排序，附 share 和用在 background/fill/text/line/shadow 哪些地方）、字体（texts 用了几段文字、largest 最大字号）和正文字号 bodySize。改文档前先 inspect，拿到节点 id / 路径再发动作。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。
| Name | Required | Description | Default |
|---|---|---|---|
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears the full burden. It strongly implies a read-only operation and details the return shape, but never states outright that the document is never modified, how behavior differs across the three input modes, or what happens on malformed/legacy documents. Adequate, but not complete for an unannotated tool.
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?
Purpose is front-loaded, followed by guidance and a resource pointer; every part of the long enumeration maps to a returned field. The single mid-section sentence is dense with parenthetical detail, but that detail has nowhere else to live without an output schema.
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 no output schema and no annotations, the description does the necessary work by enumerating the returned structure field by field and routing to dingcard://schema/freeform and get_guide('document-model') for the separate question of document authoring.
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 document/documentId/documentPath are already explained structurally, which is the baseline-3 case. The description adds nothing about the tradeoffs between passing a full document versus a documentId, even though the schema itself recommends documentId.
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 names a specific verb and resource ('检查文档结构') and enumerates exactly what is returned: page summary, recursive node tree, icon/decoration ids, and a style rollup. An agent knows precisely what this produces, but it never distinguishes itself from the similar-looking siblings get_document, check_document, and validate_document by name.
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?
'改文档前先 inspect，拿到节点 id / 路径再发动作' gives an explicit ordering rule: inspect before mutating, use the returned ids/paths for actions. What's missing is any exclusion or contrast with the other read-style siblings, so the agent isn't told when get_document or check_document would be the better choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查内置素材与样式清单，kind 选一类：icons 内置图标（query 中文或英文搜、ids 按 id 取；example 是可直接 node/insert-children 的完整 path 节点）、decorations 装饰素材（手绘线条、贴纸、标签；category 只看一类，用 add_decorations 放置）、styles 配色与字体组合（document/restyle 一键套用）、text_styles 现成花字（patch 直接作为 node/update-style 的补丁）、collages 拼图版式（example 是完整的拼图组节点，格子换图片填充）、filter_presets 照片滤镜预设（patch 同样给 node/update-style）。不给 kind 返回每类的条数和用法。
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | icons / decorations：按 id 精确取 | |
| kind | No | 素材类别；不给返回各类简介 | |
| query | No | icons / decorations：中文或英文关键词，空格分隔的多个词需同时命中 | |
| category | No | decorations：只看一类 | |
| pageWidth | No | collages：页面宽 px（默认 1080） | |
| pageHeight | No | collages：页面高 px（默认 1440） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it states the output shape per kind (path node for icons, group node for collages, style patch for text_styles/filter_presets) and the default behavior without kind. It omits anything about result caps or pagination for large asset sets, which is the remaining gap.
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?
Purpose is front-loaded and every clause maps to a distinct kind value, so little is wasted. The single dense block with nested parentheticals is harder to scan than a short bulleted breakdown would be.
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 6-param, no-annotation, no-output-schema catalog tool, it covers return shape, default behavior, and per-kind parameter relevance. What it leaves unsaid is volume/pagination behavior and whether results are cached or static.
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 which kind each parameter applies to (query/ids for icons and decorations, category only for decorations, pageWidth/pageHeight only for collages), tying parameters to concrete tasks rather than restating names.
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?
A specific verb+resource (查内置素材与样式清单) followed by a full enumeration of the kind values and what each returns. The agent can tell exactly what this tool lists and how it differs from siblings like add_decorations or list_templates.
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?
Explicitly routes the agent per use case: decorations are placed with add_decorations, icon examples go straight into node/insert-children, text_styles/filter_presets patches feed node/update-style. It also documents the no-kind default (returns per-category counts and usage) as a discovery path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出叮卡内置模板，按内容和尺寸挑模板、拿 templateId。默认每个模板一张简卡：id、标题、描述、kind、format（尺寸 id）、uses（用途）、styles（风格）。kind 是 deck（一整套，用 create_document_from_content / create_document_from_outline 生成）或 poster（单页，用 create_poster_from_content 生成）。kind / format / q 只取子集（如 kind: "poster"、format: "xhs"、q: "菜单"）。挑出两三个候选后用 ids 取详情：每页能放多少要点（capacity）、海报有哪些位置（posterCapacity）、颜色、标签和像素尺寸，字段含义见 get_guide("templates")。不同页可以用不同模板：create_document_from_content 的每页可以写自己的 templateId，add_template_pages 把任何模板的某几页加进已有文档。
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | 关键词，匹配标题、标签、用途、风格和描述（如 "菜单"、"国风"） | |
| ids | No | 要看详情的模板 id；给了就只返回这几个模板的完整信息，不看 kind / format / q | |
| kind | No | 只列这一类：deck 整套卡片，poster 单页海报 | |
| format | No | 按页面尺寸 id 筛选（不区分大小写的子串匹配，如 "xhs"、"a4"） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the default payload (id, title, description, kind, format, uses, styles) versus the richer ids payload (capacity, posterCapacity, colors, tags, pixel sizes). It omits the max-12 ids cap and doesn't explicitly state it's a read-only listing, which keeps it below 5.
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?
Front-loaded with the core purpose and payload, then filters, then the detail path. The closing sentence about per-page templateId and add_template_pages is slightly tangential to a listing tool but earns its place as routing context; overall tight with almost no filler.
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?
There is no output schema, and the description covers the return shape well for the default and ids modes. Field meanings are delegated to get_guide('templates'), which is acceptable, but an agent still lacks the full detail field list without a second call.
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 already 100%, yet the description still adds value: it explains that q matches titles, tags, uses, styles and descriptions, gives concrete examples per filter, and clarifies that ids takes precedence over the other filters.
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?
Starts with a specific verb+resource ('列出叮卡内置模板') and states its outcome ('挑模板、拿 templateId'). It also names the exact creation siblings (create_document_from_content, create_poster_from_content, create_document_from_outline, add_template_pages) with the kind each applies to, so an agent can distinguish it from every downstream 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?
Gives an explicit workflow: filter by kind/format/q, shortlist two or three, then fetch details with ids. It also states the override rule ('给了就只返回……不看 kind / format / q' in schema, echoed as subset semantics) and routes deeper field questions to get_guide('templates').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在叮卡编辑器里打开这份自由画布文档，方便人接着手改：服务端把文档放在本机地址上，在浏览器里打开编辑器的导入链接，编辑器读进来存成一个新项目（不登录也行，存在这台设备的浏览器里）。默认打开服务端自带的编辑器 http://127.0.0.1:5390（DINGCARD_APP_PORT 可改端口，被占用时换一个空闲端口）；设了环境变量 DINGCARD_APP_URL 或传 appUrl，就在那个叮卡里打开。open: false 只返回链接（url）不打开浏览器。
| Name | Required | Description | Default |
|---|---|---|---|
| open | No | 是否打开浏览器，默认 true | |
| title | No | 项目名，默认「导入的设计」 | |
| appUrl | No | 在这个叮卡编辑器里打开，如 http://127.0.0.1:5173 | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the side effect (the editor imports the doc and stores it as a NEW project in this device's browser, no login required), the port default of 5390 with DINGCARD_APP_PORT override and free-port fallback, and what open:false returns. It does not say whether repeated calls create duplicate projects or what happens if the local server cannot start, so it is 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense paragraph, front-loaded with the action and purpose, then environmental details. Every clause carries information, though the parenthetical about ports and the env-var precedence could be tightened.
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 six-parameter, all-optional tool with no output schema and no annotations, the description covers the purpose, the environment prerequisites, the side effect on the editor, and the return value when open is false. Only edge behavior (failures, repeat invocations) is left unstated.
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 schema already documents all six parameters and the baseline would be 3. The description adds real value on top: it clarifies the precedence of appUrl over the default port, the meaning of open:false as returning only the url, and that the editor persists to local browser storage — context the schema text does not convey.
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 verb and resource — opening this free-canvas document in the DingCard editor so a human can continue editing by hand — and explains the mechanism (server hosts the doc at a local address, browser opens the editor's import link, editor stores it as a new project). That is clearly distinct from siblings such as render_document (produces output) or share_document (shares a link).
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 gives a clear context for use: when a person needs to keep editing the document manually rather than programmatically. It also spells out the variants — default local editor, DINGCARD_APP_URL/appUrl override, and open:false to just get the URL. It never names a sibling tool as an alternative or exclusion, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把自由画布 v44 文档（v1–43 输入自动迁移）无头渲染为图片或 PDF（与编辑器导出同一管线：网页字体按字符子集嵌入、图片就绪等待、逐页导出），默认逐页 PNG 到 outputDir，另附每页小缩略图供你直接查看效果。长图、九宫格、PDF、JPEG、倍率等输出方式见 get_guide("render-export")。仅支持自由画布文档；文档中的图片 src 必须是浏览器可加载的 URL 或 data URL。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。
| Name | Required | Description | Default |
|---|---|---|---|
| grid | No | png / jpeg：每个正方形页面切成九宫格（九个文件），代替逐页文件 | |
| long | No | png / jpeg：所有页拼成一张长图，代替逐页文件 | |
| scale | No | 像素倍率，默认 1 | |
| format | No | png（默认，保留透明）、jpeg（白底）或 pdf（所有页在一个文件里） | |
| quality | No | jpeg 和 pdf 的 JPEG 质量，默认 0.92 | |
| baseName | No | 输出文件名前缀，默认 "dingcard" | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| previews | No | 是否附上缩略图，默认 true | |
| slideIds | No | 只渲染这些页（默认全部，按文档页序）；长图和 PDF 也只包含这些页 | |
| outputDir | Yes | 输出目录（不存在会创建） | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId |
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 discloses several non-obvious behaviors: the renderer uses the same pipeline as the editor, embeds web fonts as per-character subsets, waits for images to be ready, exports page by page, and auto-migrates v1–43 documents to v44. It omits cost or duration expectations and failure behavior for unreachable image URLs, which keeps it below 5.
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 content is front-loaded: the tool's action and default output appear first, followed by scope limits and pointers to related guides. It is dense but not padded, although the nested parentheticals and three separate cross-references make it slightly harder to scan.
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 12-parameter, annotation-free tool with no output schema, the description covers pipeline behavior, the required input constraints, and where to find more detail. However, it never says what the call returns (for example, output file paths or a thumbnail list), which is a meaningful gap when no output schema exists.
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 already documents every parameter, including format defaults, previews default true, quality range, and the document/documentId/documentPath alternatives. The description mostly restates those defaults (page-by-page PNG, thumbnails attached) rather than adding new meaning, 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 states a specific verb and resource (headlessly render freeform-canvas v44 documents to images or PDF) and immediately names its differentiators: it uses the same pipeline as the editor export, with font subsetting, image-readiness waiting, and page-by-page export. It also states the default behavior (page-by-page PNG into outputDir plus thumbnails) and the hard scope limit (only freeform-canvas documents). An agent can distinguish it from siblings such as render_markdown or open_in_editor without opening the schema.
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 gives explicit when-to-use constraints: it is only for freeform-canvas documents, and image src values must be browser-loadable URLs or data URLs. It routes the agent to get_guide("render-export") for long-image, grid, PDF, JPEG, and scale modes, and to dingcard://schema/freeform for authoring. It does not explicitly exclude sibling tools such as render_markdown, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把 Markdown 文档信封无头渲染为一套卡片 PNG（与 Markdown 工作台导出同一管线：DOM 实测分页、平台头部与主题、网页字体按字符子集嵌入、逐页 pixelRatio 3 导出）。输出 -01.png、-02.png… 到 outputDir；页数由分页决定。 document 为 Markdown 文档信封：{ source: Markdown 文本（--- 为手动分页）, platformId: 'rednote'|'weibo'|'twitter', themeId: 主题 id（如 'light'）, fontFamily, radius: 数字圆角, profile: { nickname, handle, location, avatarColor, avatarImage: dataURL 或 null, verified, headerFirstPageOnly }, images?: { "img:": dataURL } }。
| Name | Required | Description | Default |
|---|---|---|---|
| baseName | No | 输出文件名前缀，默认 "dingcard" | |
| document | Yes | Markdown 文档信封 JSON | |
| previews | No | 是否附上缩略图，默认 true | |
| outputDir | Yes | PNG 输出目录（不存在会创建） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose real behavior: file naming (<baseName>-01.png, -02.png…), page count driven entirely by pagination, non-existent outputDir being created, and default thumbnail previews. It says nothing about overwrite behavior, failure modes, permissions, or cost/latency of a headless render with font subsetting.
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?
Front-loaded with the action and output convention before the envelope spec, and every clause carries information. Some pipeline parentheticals (font subsetting, pixelRatio 3) are close to trivia for an agent's decision but do help set expectations about fidelity.
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 file-producing tool with no annotations and no output schema, the description covers output location, naming, page-count derivation, directory creation, and the full input envelope. Missing only secondary behavior: overwrite semantics, error reporting, and what the preview thumbnails actually contain.
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%, but the `document` parameter is effectively free-form JSON with no structure declared in the schema. The description compensates by enumerating the envelope: source (with '---' as manual page break), platformId values ('rednote'|'weibo'|'twitter'), themeId, fontFamily, radius, every profile field including avatarImage dataURL-or-null, and the images map keyed by 'img:<id>'. That is meaning well beyond the schema.
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?
States a specific verb and resource: headlessly render a Markdown document envelope into a set of card PNGs, and pins the exact pipeline ('same as the Markdown workbench export: DOM-measured pagination, platform header/theme, subset-embedded web fonts, pixelRatio 3 per page'). It does not, however, distinguish itself from the sibling render_document, so an agent must guess which renderer applies.
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?
There is no explicit when-to-use or when-not-to-use statement, and no sibling is named. Use is only implied by the requirement for a Markdown document envelope plus outputDir. The closest alternative, render_document, is left uncontrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
搜索在线图库的照片，给卡片配图：返回缩略图和能直接使用的图片地址，把它们填进图片字段（create_poster_from_content 的 image、图片节点的 src、页面的图片背景都接受 http(s) 地址）。配置了 DINGCARD_SERVER_URL（和账号）时走部署服务端的图库代理（Pixabay / Unsplash / Pexels / Openverse，密钥留在服务端），选中的图用 import_stock_image 转存成账号里的稳定地址；没配置时直连 Openverse（免密钥、只搜 CC0 可商用图），结果里的 url 可以直接用、无需转存。搜索词用中英文内容词都行，如 "咖啡馆 内景"、"city night skyline"。
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 页码，默认 1；一页约 12 张 | |
| query | Yes | 搜索词，如 "咖啡馆 内景"、"city skyline night" | |
| source | No | 图库源 id（服务端模式下可换源，如 pixabay / unsplash / pexels / openverse）；不填用默认源 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description carries the full burden well: it discloses that API keys stay server-side in proxy mode, that the keyless fallback is restricted to CC0 commercially usable images, that source switching is only available in server mode, and roughly 12 results per page. These are operational traits an agent cannot infer from the 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?
Purpose and return shape are front-loaded, then mode behavior, then usage tips; every clause carries information. It is a dense single block with nested parentheses, which makes it slightly harder to scan than a short bulleted structure would be.
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?
There is no output schema, yet the description explains what comes back (thumbnails plus directly usable http(s) URLs) and what to do with it. Combined with the mode-dependent behavior and key handling, an agent has everything needed to call it and consume the result 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%, so the baseline is 3; the description adds real value by noting that query works with either Chinese or English content words (with examples) and that source is only meaningful in server mode. It doesn't expand on the page parameter beyond the schema's page-size hint.
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?
States a specific verb+resource (搜索在线图库的照片) and the concrete downstream use (给卡片配图), plus what it returns (缩略图和能直接使用的图片地址). It also distinguishes itself from the sibling import_stock_image, which is the tool that persists a selected result rather than searching.
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?
Explicitly splits the two operating modes: with DINGCARD_SERVER_URL configured it goes through the server-side proxy (Pixabay/Unsplash/Pexels/Openverse) and requires import_stock_image to get a stable URL; without it, results are direct Openverse CC0 links usable as-is. It even names where the returned URLs are consumed (create_poster_from_content image, image node src, page background).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
管部署的叮卡服务端账号里存的作品（人在编辑器里存的，AI 接着做）：action 选操作——list 列出作品（id、标题、类型 mode、更新时间，query 按标题过滤，这是接着做已有作品的第一步）、open 按 id 载入（自由画布作品返回 documentId，之后 inspect_document / apply_actions / render_document / share_document 都能用；Markdown 作品返回 markdownDocument 信封，交给 render_markdown）、save 把一份文档存回账号（不给 projectId 存成新作品，给 open 返回的 projectId 时覆盖那一份）。需要环境变量 DINGCARD_SERVER_URL 加 DINGCARD_SERVER_TOKEN（带 drafts 权限的 API 令牌）或账号环境变量。
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | open：要打开的作品 id（list 里查） | |
| query | No | list：按标题关键词过滤，不区分大小写；不给就列全部 | |
| title | No | save：作品名；不给时按第一页的名称自动起 | |
| action | Yes | 要做的操作 | |
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| projectId | No | save：要覆盖的服务端作品 id（open 返回的 projectId）；不给就存成新作品 | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the auth prerequisite (DINGCARD_SERVER_URL plus a DINGCARD_SERVER_TOKEN carrying drafts permission) and the key mutation semantic that save without projectId creates a new work while supplying an open-returned projectId overwrites that existing one. It stops short of error behavior, rate limits, or what overwriting destroys, which keeps it from a 5.
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 dense sentence with a clear action-by-action structure, and the resource definition is front-loaded before the parenthetical action breakdown. It is information-rich rather than padded, though the nested parentheses and multi-clause action list make it heavier to parse than necessary.
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 9-parameter, no-annotation, no-output-schema tool, the description covers the essentials an agent needs: auth setup, per-action semantics, return-type branching, and overwrite behavior. The remaining gaps (includeDocument default, documentPath/document alternatives) are adequately handled by the fully-covered schema.
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, but the description adds real meaning where the schema is weakest — the action enum is documented only as '要做的操作', and the description instead spells out what each of list/open/save accepts and returns. It says nothing about includeDocument, documentPath, or document, leaving those entirely to the schema.
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 verb+resource: it manages works stored in a Dingcard server account, with three named operations (list/open/save), and explicitly distinguishes editor-saved works from AI-continued ones. It also names the downstream tools each result type feeds into (inspect_document / apply_actions / render_document / share_document for canvas, render_markdown for Markdown), so an agent can place it precisely among the 21 siblings.
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?
Usage is explicit and sequenced: list is called out as 'the first step to continue an existing work', open loads by id, save writes back with or without projectId. The description also gives the routing rule for two alternatives (free-canvas vs Markdown works) and says which sibling to hand each envelope to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
校验文档是否为合法的自由画布 v44 文档（v1–43 自动迁移，src 是本机路径的图片读进来嵌入）；合法时保存在服务端并返回 documentId（已有 documentId 的照旧），非法时返回原因：第几页、哪个节点、多了或缺了哪个键，或者该写哪个 documentVersion。 文档速写：{ documentVersion: 44, slides: [{ id, name, width(128–4096), height(128–4096), background, nodes, guides? }], activeSlideId }；节点 11 选一（text / image / shape / line / path / qrcode / chart / table / timeline / progress / group），公共必填键 id, name, locked, hidden, type, x, y, rotation, scale，其余键按节点类型精确匹配（不多不少），全文档节点 id 唯一。每种节点的完整键表见 dingcard://schema/freeform 资源或 get_guide("document-model")，写之前先读；拿不准就先写个大概来校验，按返回的原因改。
| Name | Required | Description | Default |
|---|---|---|---|
| document | No | 完整的 v44（或 v1–43 旧版）文档 JSON，可替代 documentId | |
| documentId | No | 创建或修改文档的工具返回的 documentId（推荐：不必来回传整份文档） | |
| documentPath | No | 文档 JSON 文件的路径，可替代 documentId | |
| includeDocument | No | 同时返回完整文档 JSON（默认只返回 documentId 和 version） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses the server-side persistence side effect, that v1–43 documents are auto-migrated, that local-path image srcs are read and embedded, and that an existing documentId is preserved. It also specifies the error payload shape (page, node, extra/missing key, suggested documentVersion). Remaining gaps are auth/permission requirements, size limits, and what happens to an existing document's prior contents on re-validation.
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 core purpose, side effect and error format are front-loaded in the first sentence, which is good. But the second half is a dense inline mini-spec that partially duplicates the dingcard://schema/freeform resource the description itself tells the agent to read, making it longer than necessary.
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?
There is no output schema and no annotations, so the description must explain returns and behavior — and it does: documentId/version on success, structured error reasons on failure, plus migration and image-embedding side effects. For a 4-parameter, zero-required tool it is close to complete; only permission and overwrite semantics are missing.
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 baseline would be 3, but the description adds real meaning for the primary `document` parameter: the v44 shape (documentVersion, slides, node type enumeration, common required keys, exact key matching, global id uniqueness) and a pointer to the authoritative schema resource. It does not add anything for documentPath or includeDocument beyond what the schema already says.
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 verb and resource: validate a freeform-canvas v44 document, and adds the key distinguishing behavior that a valid document is persisted server-side and a documentId returned. It is easy to distinguish from read-oriented siblings like get_document or inspect_document, though it never contrasts itself with the similarly-named check_document sibling, which an agent could easily confuse it with.
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 gives concrete workflow guidance: read the schema resource or get_guide("document-model") before writing, and if unsure, submit a rough draft for validation and iterate on the returned errors. That is a clear 'when to use' with an implied call pattern. It stops short of naming alternatives (check_document vs inspect_document vs this tool) or stating when validation is unnecessary.
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.
v0.1.0add_decorationsadd_template_pagesapply_actionscheck_documentcreate_document_from_contentcreate_document_from_htmlcreate_document_from_outlinecreate_document_from_templatecreate_poster_from_contentget_documentget_guideimport_stock_imageinspect_documentlist_assetslist_templatesopen_in_editorrender_documentrender_markdownsearch_imagesserver_projectsshare_documentvalidate_documentScored across 22 tools
Each tool has a well-described distinct role, but there are five creation entry points (from_content, from_outline, from_template, from_html, create_poster_from_content) whose boundaries an agent must infer from content-shape nuances, and three quality tools (validate_document= schema, inspect_document= structure, check_document= visual problems) whose names alone don't clearly separate them. The detailed descriptions do resolve most confusion, so it lands at mostly-distinct with a few confusable pairs.
A strong snake_case verb_noun convention dominates: create_*_from_*, get_document, list_templates, add_decorations, apply_actions, check_document, render_markdown, share_document. The exceptions are minor — server_projects is a bare noun multiplexed by an action param, and add_template_pages/add_decorations mix patterns but stay readable.
22 tools is on the heavy side for a card-design server, and part of that weight is genuine overlap: five separate document-creation tools plus three inspection/validation tools could be consolidated behind parameters. Every tool does earn a place in the workflow, but the surface feels broader than strictly necessary.
The lifecycle is nearly end-to-end: authoring (template/content/outline/HTML/poster), editing (apply_actions), validation/inspection/visual checking, rendering, local editor handoff, sharing, server project management, plus asset/template/stock-image discovery. Minor gaps exist — no document deletion, duplication, or local document listing — but agents can work around these.
Generate branded images at scale: design templates and render them to PNGs by prompt.
JSON in, PDF out. Render invoices, certificates, reports and cards from a template and a payload.
Render PDFs from templates you design once: list templates, check the data shape, preview, render.
Make branded PDFs and images from reusable templates, brand kits, and your data.
