Paper Physics is an MCP service for creating interactive 2D mechanics scenes for physics teaching and learning. It enables AI agents to turn interpreted problems and modeling instructions into visual scenes with blocks, ramps, pulleys, ropes, springs, and conveyor belts. Agents can edit components, apply forces, configure contact friction, process reference images, check scenes, generate visual previews, and import or export scene JSON. With numerical inputs, the service can simulate motion and
Scored across 9 tools
Most tools have clearly distinct purposes: build/update/preview/export/review operate on scenes but with different actions, and analyze_motion, prepare_reference_image, and get_build_spec are unmistakable. The only soft overlap is between inspect_scene and review_scene, both of which take a document and return information, but their descriptions clarify that one extracts structure/unknowns while the other flags issues.
Every tool name follows a consistent snake_case verb_noun pattern (analyze_motion, build_scene, export_scene, etc.). There are no style deviations or vague single-word names.
Nine tools is well-scoped for a physics scene authoring and analysis server. Each tool corresponds to a necessary operation in the workflow (spec, build, inspect, update, review, preview, export, analyze, image prep) without redundancy.
The surface covers the full local document lifecycle: get the build spec, create a scene, inspect/update it, review for correctness, preview as PNG, export as JSON, and analyze motion. Reference image preparation is also included, and no server-side storage is expected, so missing delete/list operations are not gaps.
复用网页物理引擎和参数时间轴，返回各物体位置、速度、加速度、受力、接触、弹簧状态及采样阶段。参数需为数值；不是符号求解或无限时域的完整解析解。
| Name | Required | Description | Default |
|---|---|---|---|
| bodyIds | No | 默认选运动物体；最多20个，计算仍包含全部组件。 | |
| document | Yes | ||
| duration | No | 从文档时间轴起点开始计算的秒数，默认min(时间轴时长,10)，不得超过文档结束时间。 | |
| sampleInterval | No | 返回样本间隔，单位秒，默认0.2；节点额外返回前后状态。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and closed-world behavior, and the description adds meaningful context beyond them: the simulation basis and the exact categories of state returned. It also discloses important scope limits, though it still omits execution cost or pagination behavior for the returned samples.
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 tightly packed sentences front-load the return value list and then add the key limitation. There is no redundant restatement of the title or wasted preamble.
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 enumerated return values help compensate for the absence of an output schema. However, the required document parameter is an untyped nested object with no schema description, and the description does not explain its expected structure or source, leaving a significant setup gap for an agent invoking this tool.
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%, so the schema already documents bodyIds, duration, and sampleInterval defaults/ranges. The description only adds that parameters must be numeric, which is vague and arguably misleading for bodyIds/document, and does not clarify the required document object. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (analyze motion), the computational basis (web physics engine and parameter timeline), and the returned quantities (position, velocity, acceleration, force, contact, spring state, sampling stage). It does not explicitly contrast with siblings like preview_scene or inspect_scene, but the motion-analysis resource is clearly distinct.
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 negative boundary: parameters must be numeric and this is not symbolic solving or an infinite-time-domain analytic solution. However, it does not say when to choose this over preview_scene/inspect_scene, nor does it state prerequisites such as needing a document produced by build_scene.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
传入完整 SceneSpec，按相对关系生成并检查场景，返回 document 和小场景网页链接。无草稿、文件或服务器会话；未知物理值保留符号。
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| spec | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive/closed-world. The description adds genuinely non-redundant behavior: it returns a document and a scene web link (important since there is no output schema), it is stateless with no drafts/files/server sessions, and unknown physical values are preserved as symbols rather than fabricated. Nothing conflicts with the readOnlyHint.
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?
Three short clauses, front-loaded with the action and inputs, then outputs, then constraints. Zero redundant sentences.
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 a deeply nested SceneSpec, no output schema, and no top-level parameter descriptions, the description covers the return value and statelessness well but says almost nothing about how 'checking' behaves (what constitutes a failure, whether errors are returned vs. thrown, or how relative placement is resolved). Adequate but leaves real gaps for a tool this complex.
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?
Top-level parameters (name, spec) carry no schema descriptions, so coverage is effectively 0% at that level. The description adds the key semantic that the spec must be 'complete' and that unresolved physical quantities stay symbolic, but it does not explain spec substructure (components, placement relations, intent) beyond what the nested schema itself hints at.
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: take a complete SceneSpec, generate and check the scene by relative relations, and return a document plus a scene web link. This distinguishes it reasonably from review_scene/preview_scene by emphasizing generation+checking, though it does not explicitly name any sibling.
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 clause '无草稿、文件或服务器会话' implies this is the one-shot, stateless build path and that incremental/draft workflows belong elsewhere (update_scene), but no alternative tool is named and no when-not-to-use condition is explicit. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
校验完整场景并返回application/json嵌入资源、文件名和可打开的场景链接。支持较大场景交付，不生成云端存储链接。
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| document | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and closed-world scope. The description adds valuable output context: it returns an embedded JSON resource, a filename, and an openable link, and it explicitly states it does not generate cloud storage links. No contradictions with 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?
Two tightly written sentences that front-load the core action and negative constraint. No filler, every clause adds information.
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?
Without an output schema, the description does a fair job of covering return values (embedded JSON, filename, link) and one negative constraint. But the input schema is rich (nested object, two params) and the description adds almost nothing about parameter semantics, leaving a completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for two parameters, so the description must carry the burden. It only vaguely implies that the required 'document' is the full scene to validate, and it never mentions the optional 'name' parameter or format expectations.
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 a specific action: validate the full scene and return an application/json embedded resource, filename, and openable scene link. It distinguishes itself from siblings like build_scene or inspect_scene by focusing on export, but does not explicitly name any alternative.
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 implies appropriate use for larger scene delivery and notes that cloud storage links are not generated, which hints at when to choose otherwise. However, no sibling tool is named and no explicit when-to-use or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
一次获取组件目录、SceneSpec 和场景文档契约、相对布局示例、检查方式及云端构建流程。示例数值不代表题设。
| Name | Required | Description | Default |
|---|---|---|---|
| types | No | 可选组件过滤，例如 block、belt、arc；不填返回全部。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds one behavioral nuance beyond that: the returned example values are illustrative and must not be treated as the task specification. It says nothing about auth, rate limits, or whether the spec is static or regenerated per request.
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 that front-loads the retrieval action and then lists the payload contents, followed by a short caveat. Dense but not padded; the only cost is that the enumeration is a comma run-on rather than structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing the return, and it does enumerate the artifact categories returned. Combined with annotations covering the read-only/idempotent profile, an agent has enough to call it correctly, though it doesn't explain the shape of each artifact or how they relate.
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% and the single 'types' filter is fully documented in the schema itself, so the baseline is 3. The description does not mention the filtering parameter at all, adding no 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 names a specific retrieve action and enumerates what is returned (component catalog, SceneSpec/document contract, layout examples, inspection methods, cloud build process), so the agent knows exactly what this tool produces. It does not explicitly contrast itself with siblings like build_scene or inspect_scene, but 'get_build_spec' plus the enumerated payload makes the distinction inferable.
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 when-to-use statement, no prerequisites, and no named alternative among the eight sibling tools. The only usage-relevant hint is the caveat that sample values are not the actual problem, which is a warning about content rather than guidance on invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
传入网页导出的完整JSON对象，读取组件、连接、外力、接触与时间节点；列出未知符号、数值分析条件和默认参数。JSON保存初始配置和参数修改，不含完整轨迹。
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | 网页导出或工具返回的完整SceneDocument对象，不能填写本机路径或JSON字符串。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly=true, idempotent=true, openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: the JSON holds initial configuration and parameter modifications but not full trajectories, which tells the agent what will and will not be found in the result.
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 front-loads the input requirement before the extraction list, so the critical calling convention is not buried. The semicolon-chained enumeration is slightly list-like but every clause 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?
With no output schema, the description must carry the return contract, and it does: it names the categories of data that will be read out and listed. For a one-parameter read tool this is nearly complete, missing only format/structure hints for the returned data.
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 schema already states the value cannot be a local path or JSON string. The description nevertheless adds content-level semantics for the single parameter (it is a complete webpage-exported JSON object) plus a boundary note that trajectories are absent, going 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 states a specific verb (读取/read) and resource (网页导出的完整JSON对象) and enumerates exactly what is extracted: components, connections, external forces, contacts, time nodes, unknown symbols, analysis conditions, default parameters. This distinguishes it from write-oriented siblings like build_scene/update_scene/export_scene, but it never names a sibling or explicitly contrasts itself, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: pass the JSON exported from the webpage to inspect its contents. There is no explicit when-to-use, when-not-to-use, or routing statement (e.g. 'use analyze_motion to obtain trajectories instead'), leaving the agent to infer which sibling is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取PNG/JPEG，返回实际PNG图片。支持EXIF朝向、裁剪、顺时针旋转、四角透视校正和缩放；默认保持原方向、比例与内容。图片来源三选一。
| Name | Required | Description | Default |
|---|---|---|---|
| crop | No | ||
| dataUrl | No | data:image/png;base64,... 或 data:image/jpeg;base64,... | |
| maxSide | No | ||
| imageUrl | No | 可公开访问的HTTPS图片地址，最多4MB。 | |
| rotation | No | 顺时针角度，默认不旋转。 | |
| imageData | No | PNG/JPEG的Base64字节，不填写本机文件路径。 | |
| autoOrient | No | ||
| perspective | No | EXIF朝向修正、裁剪和rotation之后的图片像素坐标；按左上、右上、右下、左下排列。 | |
| includeDataUrl | No | 需要继续传入预览时才设true；默认仅返回MCP图片内容。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond them: the output contract ('返回实际PNG图片', important since there is no output schema) and the no-op default ('默认保持原方向、比例与内容'), which tells the agent that omitting parameters yields the untouched image. It still omits failure behavior for unreadable or oversized images.
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?
Three compact sentences that lead with input/output, then capabilities, then the default, then the source constraint — well ordered with no filler. The telegraphic final fragment '图片来源三选一' is efficient but borders on underspecified.
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 tool with nesting and no output schema, the description covers the essential shape: what comes in, what comes out, and the no-transform default. It is nonetheless thin on the three mutually exclusive sources, error/limit behavior, and how the prepared image is meant to be consumed downstream, leaving open questions against a fairly complex 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 description coverage is 67%, so the schema documents most parameters; the description only maps capability names to operations (EXIF/crop/rotation/perspective/scaling) without adding semantics such as what maxSide bounds or how the source parameters interact. With mid-to-high coverage and a genuinely detailed schema, 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?
States concrete verbs and resource: reads PNG/JPEG and returns a real PNG image, then enumerates the supported transforms (EXIF orientation, crop, clockwise rotation, four-corner perspective, scaling). The purpose is unambiguous and clearly separable from the scene-building siblings, but the description never names or distinguishes itself from any sibling, and the title's '题目图片' framing is not carried into the description.
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?
'图片来源三选一' signals that exactly one of the three source inputs should be supplied, which is real usage guidance, and the default-preserving clause implies the tool is a pass-through unless transforms are requested. However, there is no explicit statement of when to reach for this tool (e.g., before passing an image to preview_scene) versus other approaches, and no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按共享组件几何生成实际PNG预览；可提供reference题图，返回左题图、右场景的对照图和编号对应组件ID。输入完整document，不依赖服务器草稿。
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | ||
| height | No | ||
| document | Yes | ||
| reference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/openWorld/idempotent, and the description adds real value on top: it discloses the return content (comparison image layout plus numbered component IDs) and an important constraint ('不依赖服务器草稿' – the full document must be supplied rather than relying on a server-side draft). It does not cover failure/limit behavior, but the additions are meaningful given 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?
Three tight, front-loaded clauses lead with the core action (generate PNG preview) before covering the optional reference and the input constraint. No filler; dense but each clause 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?
For a moderately complex tool (nested reference object, no output schema), the description adequately conveys inputs, the optional comparison mode, and the returned artifacts. The gaps are minor – width/height semantics – and the nested reference fields are documented in the schema itself.
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?
Top-level schema description coverage is 0%, so the description must carry the burden; it clarifies the meaning of 'document' (full document input) and 'reference' (optional comparison image). However, it says nothing about the width/height sizing parameters, so compensation is only partial, leaving half the top-level parameters unexplained.
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: generate an actual PNG preview from shared component geometry, and it describes the output (left reference / right scene comparison plus numbered component IDs). It clearly distinguishes the preview/compare role from siblings like export_scene or build_scene, though it never names an alternative 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?
It gives one conditional cue ('可提供reference题图' – optionally supply a reference image for comparison) and a prerequisite ('输入完整document'), but it offers no explicit when-to-use/when-not guidance against the many related siblings (export_scene, review_scene, inspect_scene). Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
传入完整文档和可选几何意图，独立检查组件清单、接触、轨道连接和方向，返回具体问题；不改变输入。
| Name | Required | Description | Default |
|---|---|---|---|
| intent | No | Agent-provided object inventory and geometric intent after reading the normalized image; this schema does not perform image recognition. | |
| document | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so 'does not change input' is largely redundant. The genuinely additive detail is that it returns concrete issues and runs an 'independent' check (no dependence on prior build state), but the format/scope of returned issues is not described.
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 tight sentence that front-loads inputs, then the checks performed, then the return value and the non-mutation guarantee. No filler, though the phrasing bundles four check types into a list without prioritization.
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, the description should explain what the returned 'issues' look like (codes, severities, locations), which it doesn't. It is adequate for invocation — the inputs and check scope are clear — but an agent cannot predict the response shape or what happens on a clean scene.
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 50% and the two parameters map directly to 'complete document' and 'optional geometric intent,' which the description restates without adding meaning. The deeply nested intent schema already documents contacts, connections, expectedEntities, and inventoryComplete, so the description needn't repeat them — but it also contributes nothing new about how intent influences the checks.
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 (独立检查/independently check) and enumerates the resources reviewed: component inventory, contacts, track connections, orientation, plus what it returns (specific issues). It distinguishes itself from build/update siblings by emphasizing it does not modify input, though it doesn't name the closest read-only siblings like inspect_scene or analyze_motion.
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 — pass a full document plus optional geometric intent to validate a scene — but there is no explicit when-to-use vs when-not, nor a pointer to inspect_scene/analyze_motion as alternatives. An agent must infer the boundary from the siblings' names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
传入上次返回的完整 document 和 patch，按 id 合并或显式删除后重新布局与检查。返回新 document；不保存状态、不使用 draftId。尺寸变化后需跟随的组件一起提供 placement。
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| document | Yes | 上次工具返回的完整 SceneDocument，包含 version、scene、time 等。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds meaningful behavior beyond that: it does not persist state, does not use a draftId, returns a new document, and performs a re-layout/check pass. The note that follow-on components must include placement when dimensions change is useful operational 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?
Three information-dense sentences with the merge/delete semantics front-loaded and the non-persistence and placement caveats following. Every clause carries operational meaning, though the packing is tight enough that a reader must parse carefully; it stays within the appropriate size for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description appropriately states that a new document is returned. For a nested-object patch tool with 50% schema coverage the description covers the essential call semantics and state-behavior caveats, though the placement requirement is mentioned without full detail on where it belongs in the patch.
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?
With 50% schema coverage, the description carries real weight: it clarifies that `document` is the full SceneDocument from the previous call and that `patch` is applied by id merge with explicit deletion via the remove structure. The added semantics (merge-by-id, dimension-change/placement coupling) go beyond the raw schema, though it does not map every patch subfield.
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 precise verb-and-resource operation: take the previously returned full document plus a patch, merge by id or explicitly delete, then re-layout and re-check. This clearly distinguishes it from siblings like build_scene (full construction) and inspect_scene (read-only inspection), so an agent can identify the incremental-update tool 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?
It gives the prerequisite that the input must be the document returned by the last call and that a patch must accompany it, which implies when this tool applies. However, it never explicitly contrasts with build_scene or preview_scene, nor states when NOT to use it, so the routing guidance is only implied.
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.
build_scene2 fields changedInput schema / properties / spec / properties / components / items / properties / type / enumPrevious value: -[
- "block",
- "ball",
- "floor",
- "ramp",
- "arc",
- "wall",
- "pulley",
- "movablePulley",
- "anchor"
-]New value: +[
+ "particle",
+ "block",
+ "ball",
+ "floor",
+ "ramp",
+ "arc",
+ "wall",
+ "pulley",
+ "movablePulley",
+ "anchor"
+]Input schema / properties / spec / properties / intent / properties / expectedEntities / items / properties / type / enumPrevious value: -[
- "block",
- "ball",
- "floor",
- "ramp",
- "arc",
- "wall",
- "pulley",
- "movablePulley",
- "anchor",
- "belt",
- "rope",
- "spring"
-]New value: +[
+ "particle",
+ "block",
+ "ball",
+ "floor",
+ "ramp",
+ "arc",
+ "wall",
+ "pulley",
+ "movablePulley",
+ "anchor",
+ "belt",
+ "rope",
+ "spring"
+]review_scene1 field changedInput schema / properties / intent / properties / expectedEntities / items / properties / type / enumPrevious value: -[
- "block",
- "ball",
- "floor",
- "ramp",
- "arc",
- "wall",
- "pulley",
- "movablePulley",
- "anchor",
- "belt",
- "rope",
- "spring"
-]New value: +[
+ "particle",
+ "block",
+ "ball",
+ "floor",
+ "ramp",
+ "arc",
+ "wall",
+ "pulley",
+ "movablePulley",
+ "anchor",
+ "belt",
+ "rope",
+ "spring"
+]analyze_motionbuild_sceneexport_sceneget_build_specinspect_sceneprepare_reference_imagepreview_scenereview_sceneupdate_scene
Add one secure layer between your agents and this server.