JSON 조작을 통해 tldraw .tldr 파일을 편집하기 위한 최소한의 MCP 서버입니다. 헤드리스 방식이며 브라우저가 필요하지 않습니다.
작동하는 스켈레톤입니다. 스키마 유효성 검사가 연결되어 있으며(@tldraw/tlschema 유효성 검사기가 모든 쓰기 작업 전에 실행됨), 분수 인덱싱은 @tldraw/utils를 사용하고, 파일 쓰기는 proper-lockfile로 보호됩니다. 출력은 계약 테스트 계층에서 Store.loadStoreSnapshot()을 통해 실제 tldraw 런타임과 비교하여 엔드투엔드로 검증되었습니다.
Related MCP server: obsidian-codex-mcp
도구 | 기능 |
| 기본 페이지가 포함된 새로운 |
| 새 페이지 추가 |
| id, 이름, 정렬 인덱스가 포함된 페이지 목록 표시 |
| 도형 이동; |
도구 | 기능 |
| 직사각형(geo 도형) 생성 |
| 텍스트 도형 생성 |
| 도형을 재부모화하여 그룹화 |
| 그룹을 해제하고 자식 도형을 그룹의 부모로 재부모화 |
| 같은 페이지에 있는 두 도형 간의 화살표 + 바인딩 연결 |
| 도형 목록 표시 — id, type, x, y, label만 표시 |
| id별로 하나의 도형에 대한 전체 레코드 가져오기 |
| 얕은 병합 패치 (속성 편집을 위해 중첩된 |
| id별로 삭제; |
tldraw-mcp-app에서 영감)도구 | 기능 | 토큰 비용 |
| 지원되는 도형 유형 + 필수 속성 목록 표시. | |
| 파일에 대해 | 가변 |
도구 | 기능 | 토큰 비용 |
|
| |
| 백업 목록 표시 (최신순) | |
| 백업 복원 ( |
토큰 절약 설계: 도구는 기본 인수를 취하고 id 또는 ok를 반환합니다. 전체 JSON은 get_shape를 의도적으로 호출할 때만 컨텍스트에 들어옵니다.
npx (설치 불필요, 권장)npx -y github:m9810223/tldraw-mcp첫 실행 시 클론하고 npm install을 실행한 다음, dist/를 빌드하는 prepare 스크립트를 트리거합니다. 이후 실행은 캐시됩니다.
브랜치 / 태그 / 커밋 고정:
npx -y github:m9810223/tldraw-mcp#main
npx -y github:m9810223/tldraw-mcp#v0.1.0
npx -y github:m9810223/tldraw-mcp#abc1234npm install -g github:m9810223/tldraw-mcp
tldraw-mcp # the bin is on PATHnpx -y git+ssh://git@github.com/m9810223/tldraw-mcp.gitgit clone https://github.com/m9810223/tldraw-mcp.git
cd tldraw-mcp
npm install
npm run build
node dist/index.js # stdio MCP — waits on stdinNode.js ≥ 20 (engines.node에 의해 강제됨)
PATH에 jq 필요 (exec_jq 도구에만 필요)
macOS: brew install jq
Debian/Ubuntu: sudo apt-get install -y jq
claude mcp add (권장). -- 구분 기호가 필요하므로 -y가 claude mcp add 플래그로 파싱되지 않고 npx로 전달됩니다:
claude mcp add tldraw -- npx -y github:m9810223/tldraw-mcp전역(모든 프로젝트)의 경우 -s user를, 저장소에 체크인된 .mcp.json의 경우 -s project를 추가하세요. 기본값은 -s local (현재 프로젝트, 사용자 컴퓨터)입니다.
…또는 .mcp.json (프로젝트) / ~/.claude.json (사용자 전역)을 편집하여 설정:
{
"mcpServers": {
"tldraw": {
"command": "npx",
"args": ["-y", "github:m9810223/tldraw-mcp"]
}
}
}옵션 2를 사용하여 전역으로 설치한 경우:
{
"mcpServers": {
"tldraw": { "command": "tldraw-mcp" }
}
}Claude Code를 재시작하면 /mcp 명령어를 통해 17개의 도구가 포함된 tldraw 서버가 나열되어야 합니다.
JSON 구조는 동일하며 설정 파일 위치만 다릅니다:
클라이언트 | 설정 경로 |
Claude Desktop |
|
Cursor |
|
VS Code |
|
.tldr 파일 부트스트래핑create_empty_file 도구를 사용하거나 tldraw.com에서 빈 캔버스를 저장한 후 도구에서 절대 경로를 지정하세요.
create_empty_file({ file: "/tmp/demo.tldr" })tldraw-mcp-app과의 설계 비교Cloudflare에서 호스팅되는 공식 MCP는 search + exec(실시간 tldraw 에디터에서 JS 실행)만 노출합니다. 이 스켈레톤은 정반대의 방식인 .tldr 파일에 대한 타입 지정 JSON 편집을 수행하며, 타입 지정 도구가 작업을 다루지 못할 때 LLM이 사용할 수 있도록 탐색 패턴(search_api)과 탈출구(exec_jq)를 차용했습니다.
공식 | 이 스켈레톤 | |
전송 방식 | streamable-http + sse (Cloudflare) | stdio (Claude Code에서 직접 작동) |
런타임 | 위젯 iframe 내 실제 tldraw 에디터 | 순수 Node, 원시 JSON 편집 |
도구 | 2개 ( | 17개: 파일/페이지 수명 주기 + 도형 작업 9개 + search_api + exec_jq + ckpt |
실시간 미리보기 | 예 (위젯 iframe) | 아니오 (tldraw에서 파일을 열어 확인) |
커버리지 | 전체 에디터 API | Geo / 텍스트 / 화살표 + jq 탈출구 |
index (z-order)는 현재 최대값 위로 추가하는 것만 지원하며, 중간 삽입은 지원하지 않음
정렬 / 배분 도구 없음 (update_shape를 사용하여 x/y를 직접 설정하거나 exec_jq 사용)
이미지 / 비디오 / 에셋 지원 없음
스키마 버전 고정은 정보 제공용일 뿐이며, 더 최신 버전의 tldraw에서 파일을 열면 마이그레이션이 트리거될 수 있음
search_api 큐레이션 목록은 실시간 @tldraw/tlschema 리플렉션과 함께 수동으로 유지 관리됨
src/
index.ts MCP server entry, tool registration (stdio transport)
tools.ts Tool handlers + zod input schemas
shapes.ts tldraw record factories (geo/text/arrow/group/binding)
store.ts Load/save .tldr + withFileLock; helpers (id gen, indexing, find, page-of-shape, bindings-for-shape)
template.ts Empty .tldr generator using @tldraw/tlschema serialize()
validate.ts validateShape / validateBinding using createShapeValidator + createBindingValidator
checkpoint.ts Timestamped backups under .tldraw-mcp-checkpoints/
jq.ts Shell-out to jq for the exec_jq escape hatch
test/
unit/ store + validate (13 tests)
integration/ tools end-to-end on tmp .tldr (18 tests)
contract/ loadStoreSnapshot against real @tldraw/store (4 tests)순수 JSON 조작 — @tldraw/store, DOM, React 없음.
Connect two shapes with an arrow. Arrow position is binding-driven (start/end stored as 0,0 fallback). Returns arrow id + binding ids.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| fromId | Yes | Source shape id | |
| toId | Yes | Target shape id | |
| text | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It notes 'arrow position is binding-driven (start/end stored as 0,0 fallback)' and that it returns 'arrow id + binding ids', which adds transparency. However, it omits details like side effects on existing connections or permission needs.
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?
Two concise sentences. Front-loaded with the core action. No extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the purpose, a key behavioral trait, and the return value. It is adequate for the tool's simplicity, though more detail on binding behavior could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (three of four parameters have descriptions). The description does not explain the 'text' parameter or add meaning beyond the schema. The return value note is helpful but not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (connect two shapes with an arrow) and the resource (shapes). It distinguishes from sibling creation tools like create_rect or create_text, as it specifically adds a connection between existing shapes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., shapes must exist) or conditions that would make other tools (like update_shape) more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new empty .tldr file with one default page. Errors if file exists unless overwrite=true.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| overwrite | No | If false (default), error when file already exists |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses the key behavioral trait: creating an empty file with one default page and error handling. It is transparent about the overwrite behavior, though it could further clarify what 'default page' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the core action and key condition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description provides all necessary information for correct invocation: file path requirement and overwrite option. Complete for the task.
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 baseline is 3. The description adds value by explaining the purpose of overwrite (error prevention) and the file content (one default page), which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('new empty .tldr file'), and distinguishes from sibling tools like create_page or create_rect by targeting file creation rather than shapes or pages.
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 explicitly states the behavior when the file exists (errors) and how to override (overwrite=true), providing clear usage context. It does not explicitly mention alternatives or when not to use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Group existing shapes into a new group. Reparents the given shape ids under a new group shape.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| childIds | Yes | Shape ids to reparent into the new group |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description correctly states that the tool reparents shapes under a new group, indicating a mutation. However, it does not disclose potential side effects such as ordering, property preservation, or error conditions.
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?
Two sentences with no unnecessary words. The first sentence states the action, the second clarifies the mechanism. Highly efficient.
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?
Missing output schema means the agent needs to know what the tool returns (e.g., new group ID). The description does not mention return value, success indicators, or error handling, leaving a significant 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 covers 100% of parameters with descriptions. The description echoes the schema's 'reparent' phrase but adds minimal new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool groups existing shapes into a new group by reparenting given shape ids. This distinguishes it from siblings like ungroup (reverse) and other shape creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. While the sibling tool 'ungroup' implies the reverse operation, the description does not clarify prerequisites or alternatives for grouping tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new page in the document. Returns the new page id.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| name | Yes | Display name for the page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only states the mutation (create) and return value, lacking details like side effects, whether it modifies in-place, or if it automatically saves checkpoints.
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?
Single sentence, zero wasted words. Front-loaded with purpose and return value.
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?
Core purpose and return value are covered, but given the range of sibling tools, more context (e.g., that pages are top-level containers, or that the file must exist) would help prevent misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and resource 'page in the document', distinguishing it from siblings like create_group or create_rect. However, 'the document' could be more specific, though the file parameter clarifies it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as create_rect or create_text. No mention of prerequisites (e.g., file must exist) or context about pages as containers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a rectangle shape on the main page. Returns its id.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| x | Yes | ||
| y | Yes | ||
| w | Yes | ||
| h | Yes | ||
| text | No | ||
| color | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the basic function and return, omitting important behavioral aspects such as error handling, side effects, permissions, or constraints (e.g., coordinate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and front-loaded with the purpose. However, it lacks structure such as sections for parameters or usage notes, but it avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain parameter details, return value format, error conditions, or how it fits with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameters beyond what is in the schema. With only 14% schema description coverage, the description fails to compensate, leaving 6 out of 7 parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create), the resource (rectangle shape), the location (on the main page), and the return value (Returns its id). It distinguishes this tool from siblings like create_text or create_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or when not to use it. For example, it does not mention that the file must exist or that coordinates should be within bounds.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a text shape on the main page. Returns its id.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| x | Yes | ||
| y | Yes | ||
| text | Yes | ||
| size | No | ||
| color | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description only mentions output ('Returns its id') but does not disclose whether the tool modifies the file, any side effects, permissions required, or constraints. For a tool with no annotations, the description carries the full burden and is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence that front-loads the action and result. It is concise, but could benefit from slightly more detail without becoming 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?
With 6 parameters and no output schema, the description is too minimal. It lacks context about the file requirement, parameter usage, behavior, and potential errors, making it incomplete for reliable tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only 'file' has a description). The description does not add any explanation for parameters like 'x', 'y', 'text', 'size', 'color', leaving the agent without necessary context for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('text shape'), and the location ('on the main page'). It also mentions the return value ('Returns its id'). This distinguishes it from sibling tools like 'create_rect' or 'create_group'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it differs from other creation tools (e.g., 'create_rect', 'create_group').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a shape by id.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| id | Yes | ||
| cascade | No | Also remove related arrow bindings and arrow shapes that lose all bindings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as side effects (e.g., cascade deletion), error conditions, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence), but the brevity sacrifices informativeness. It could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain the 'cascade' parameter, required file path, or return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about parameters beyond what the schema already provides. With schema coverage at 67%, the missing 'id' parameter description is not addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('shape') and the identifier ('by id'). It distinguishes from sibling tools like update_shape or get_shape through the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other shape-related tools (e.g., update_shape, get_shape) or potential prerequisites (e.g., file must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: run a jq filter against the .tldr JSON. Set write=true to persist (auto-checkpoints first).
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| filter | Yes | jq filter expression | |
| write | No | If true, write the filter result back to the file. If false, return result only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavior: auto-checkpoints before persisting, and distinguishes between preview (write=false) and modification (write=true). With no annotations, this provides useful behavioral context beyond the raw 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?
Two sentences, no wasted words. The first sentence delivers the core purpose, the second provides key usage guidance. Appropriately front-loaded.
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?
Covers inputs and write behavior thoroughly. Lacks output description, but as an escape hatch returning jq output, this is acceptable. With no output schema, some return info would be nice but not critical.
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 is 3. The description adds value by explaining the write parameter's effect (persist) and the auto-checkpoint behavior, which is not in 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 clearly states it runs a jq filter against .tldr JSON content, with the phrase 'Escape hatch' indicating a generic powerful tool. This distinguishes it from sibling tools which are all specific to shapes, pages, or checkpoints.
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 explains when to set write=true (to persist) and notes auto-checkpointing, providing clear context for the write parameter. However, it does not mention when not to use this tool or suggest alternatives, though as an escape hatch it is intentionally broad.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full record of a single shape by id.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Get' implies a read-only operation, the description does not explicitly state it is non-destructive or safe. This is a minor gap for a simple retrieval 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?
The description is a single, well-structured sentence of 10 words. It is concise and front-loaded, immediately conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool without an output schema, the description is adequate but minimal. It does not explain what a 'full record' includes or any return format. Given low complexity, this is acceptable but could be improved.
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 50% (only 'file' has a description). The description adds no additional meaning for parameters; notably, the 'id' parameter lacks any description in both schema and description. The description fails to compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'full record of a single shape', and the method 'by id'. It effectively distinguishes from sibling tools like 'list_shapes' which retrieve multiple shapes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a shape by ID but provides no explicit guidance on when to use this tool versus alternatives like 'list_shapes' or 'update_shape'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List checkpoint backups for a .tldr file, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden; it conveys the operation is a read-only list with ordering, but does not mention error behavior (e.g., missing file) or limitations.
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?
Single sentence, no unnecessary words, front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description is nearly complete; only lacking a brief mention of what a checkpoint is or how to interpret results.
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 already describes the parameter; the description adds nothing beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'checkpoint backups for a .tldr file', and the ordering 'newest first', distinguishing it from sibling tools like 'save_checkpoint' and 'restore_checkpoint'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing backup history but does not explicitly state when to use this tool versus alternatives (e.g., when you need to restore a checkpoint) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all pages with id, name, and ordering index.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read operation but lacks details on side effects, authorization, or limits.
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?
Single sentence, front-loaded with verb and result fields. Efficient but bare-minimum.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description is mostly adequate, though it does not specify output format or pagination.
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 baseline is 3. The description adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (pages), and returned fields (id, name, ordering index). It differentiates from sibling tools like list_shapes and list_checkpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no context or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List shapes (id, type, x, y, label only - props omitted to save tokens).
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| type | No | Filter by shape type (geo, text, arrow, ...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses that props are omitted to save tokens, indicating a lightweight listing. However, it does not mention that the tool is read-only or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the tool's purpose and key constraint (props omitted). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and sibling tools, the description adequately covers what the tool returns and its filtering capability. It could mention if there is no pagination or limit.
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?
Input schema coverage is 100%, so parameters are already documented. The description adds no extra meaning 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?
The description clearly states 'List shapes' with the specific fields returned (id, type, x, y, label). It distinguishes from sibling tools like get_shape (single shape) and update_shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_shape for full details) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move shapes to a different page by reparenting them. Note: arrows and bindings should move together for correctness.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| shapeIds | Yes | ||
| pageId | Yes | Target page id | |
| bindings | No | How to handle bindings whose other end isn't being moved: 'error' refuses the move, 'pull' drags the connected shapes along, 'cut' deletes the bindings (and orphan arrows). | error |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It explains reparenting and warns about arrows/bindings, but lacks details on side effects, undoability, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core operation and a key nuance, but omits return value, prerequisites (file/ shapes exist), and error conditions. Adequate for simple usage but incomplete for complex scenarios.
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?
Description adds minimal value beyond schema: only a note about bindings reinforcing the enum descriptions. Parameters like file, shapeIds, pageId are not elaborated beyond 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?
Description clearly states the action: move shapes to a different page by reparenting. It distinguishes from sibling tools like delete_shape or update_shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_shape or delete_shape. Does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a checkpoint over the .tldr file. Omits checkpoint to restore the most recent.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| checkpoint | No | Checkpoint path; omit to restore the most recent |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'restore over', implying overwriting the file, but does not disclose side effects (e.g., irreversible changes), required permissions, or what happens to the current state. This lack of behavioral detail leaves the agent guessing about the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences—first defines the main action, second clarifies the optional parameter. No redundancy, no wasted words, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no nested objects, no output schema), the description is adequate but incomplete. It does not explain return values, error conditions, or whether the operation is destructive. Additional context would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described adequately. The description's second sentence aligns with the schema's optional parameter note but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Restore a checkpoint') and the resource ('.tldr file'), with the additional detail that omitting the checkpoint restores the most recent. This effectively distinguishes it from siblings like save_checkpoint and list_checkpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when wanting to revert to a checkpoint, but provides no explicit guidance on alternatives, prerequisites, or when not to use this tool. It does not mention siblings or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy the .tldr file to a timestamped backup. Returns the backup path.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| label | No | Optional human-readable tag (becomes part of filename) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the copy operation and return of backup path. It doesn't specify error handling or behavior if file missing, but for a simple copy, it's mostly transparent.
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?
Two short sentences with no wasted words. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers the basic operation. It misses potential details like error handling or prerequisites, but is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema; the 'label' parameter is already described in the schema as 'Optional human-readable tag (becomes part of filename).'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('copy'), resource ('.tldr file'), and outcome ('timestamped backup, returns path'). It distinguishes from sibling tools like restore_checkpoint and list_checkpoints by specifying the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating backups but does not explicitly state when to use it versus alternatives like restore_checkpoint or when not to use it. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported tldraw shape types and their required props. Use this to discover what can be created before falling back to exec_jq.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional substring to filter shape types | |
| type | No | When verbose=true, the specific shape type to introspect | |
| verbose | No | If true, dump the live prop names from @tldraw/tlschema for the given type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. 'List' implies a read-only operation, but the description does not explicitly state that there are no side effects or destructive actions. Basic transparency is present but could be improved.
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?
Two sentences, no filler, front-loaded with the core action. Every word earns its place.
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 does not explain the return format or default behavior (e.g., what happens when verbose=false). It provides a general idea but lacks details needed for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds overall context but does not deepen understanding beyond what the schema already provides. 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?
Description uses specific verb 'List' and resource 'supported tldraw shape types and their required props', clearly defining the tool's purpose. It also distinguishes from sibling exec_jq by suggesting use before falling back.
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?
Provides a clear usage hint: 'Use this to discover what can be created before falling back to exec_jq.' This tells the agent when to use this tool versus alternatives, though it could be more explicit about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dissolve a group: reparent its children to the group's parent and delete the group shape.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| groupId | Yes | Group shape id to dissolve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavior: children are reparented to the group's parent and group is deleted. Lacks details on edge cases (no parent), but sufficient given no annotations.
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?
Single sentence conveys all essential information without redundancy. Front-loaded action verb 'dissolve'.
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?
Adequately describes behavior for a simple mutation tool with two clear parameters. No output schema, so no expectation to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters fully (100%). Description does not add extra meaning beyond parameter names and types. 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?
Description uses specific verb 'dissolve' and resource 'group', clearly stating it reparents children and deletes the group. Distinguishes from sibling 'delete_shape' which would not reparent children.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use instructions. No mention of alternatives like 'delete_shape' or 'create_group'. Usage is implied by description but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a shape via shallow merge. Pass nested {"props": {...}} to update props.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute path to a .tldr file | |
| id | Yes | ||
| patch | Yes | Partial shape fields to merge (top-level or nested under "props") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions 'shallow merge', which implies top-level field overwrites but not deep merging, and clarifies updating props via nested object. However, it does not disclose side effects, idempotency, or permission requirements, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loaded with the action, and no redundant information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation and key nuance (shallow merge), but lacks details on return values, error states, or prerequisites. Given the tool's simplicity and absence of output schema, it is minimally adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the input schema by explaining that patch supports 'shallow merge' and how to update nested props. This compensates for the schema's 67% description coverage, but the 'id' parameter remains undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'shape', specifying the method as 'shallow merge'. It effectively distinguishes from sibling tools like create_shape, delete_shape, and get_shape by implying a mutation operation on an existing shape.
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 does not provide guidance on when to use this tool versus alternatives, such as move_to_page or delete_shape. It lacks explicit when-to-use, when-not-to-use, or prerequisite information.
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.0connectcreate_empty_filecreate_groupcreate_pagecreate_rectcreate_textdelete_shapeexec_jqget_shapelist_checkpointslist_pageslist_shapesmove_to_pagerestore_checkpointsave_checkpointsearch_apiungroupupdate_shapeScored across 18 tools
Each tool has a clearly distinct purpose, from creating shapes and pages to managing checkpoints and connecting shapes. The exec_jq escape hatch is intentionally broad but its role as a fallback is well-documented, avoiding confusion.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_rect, list_pages, update_shape). No mixed conventions or ambiguous verbs.
With 18 tools, the set is well-scoped for a drawing application: it covers shape CRUD, grouping, pages, checkpoints, and an escape hatch. The count feels complete without being overwhelming.
The toolset covers core operations but misses explicit tools for creating non-rectangle shapes (e.g., ellipses, lines). However, search_api and exec_jq fill these gaps, so agents can still achieve full functionality.
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
A simple MCP server built with FastMCP and python