paperphysics

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so safety is covered. The description adds value by disclosing that the result is a physics-simulated state vector across a timeline and that it is not an analytical/symbolic solution — context the annotations do not provide. It stops short of noting computational cost or determinism.

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 dense sentences with no filler; the core operation is front-loaded before the scope caveat. Every clause carries information about behavior or constraints.

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 whose input includes a nested, undocumented 'document' object and which has no output schema, the description does describe return contents well. But it never explains what 'document' is or how it should be obtained (presumably from a scene-building sibling), leaving a notable gap for correct 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 coverage is 75%, so most parameters are documented in the schema (duration, sampleInterval, bodyIds constraints). The description only adds '参数需为数值', which is somewhat imprecise since bodyIds is an array of string IDs, and it does not clarify the opaque 'document' parameter. 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 a specific verb+resource: it reuses the planar physics engine and parameter timeline to analyze motion state, and enumerates the returned quantities (position, velocity, acceleration, force, contact, spring state, sampling stage). Purpose is clear, though it does not explicitly contrast itself with scene-building siblings such as build_scene or inspect_scene.

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 provides a scope boundary ('不是符号求解或无限时域的完整解析解') that tells the agent when this tool is NOT appropriate, which is useful. However, it gives no positive 'when to use' trigger nor names an alternative sibling for comparing motion vs. static inspection.

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

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

Annotations already declare readOnlyHint/idempotentHint/closed-world, and the description reinforces this with concrete behavioral facts: no drafts, files, or server sessions are created (stateless, pure computation), and unknown physical values are preserved as symbols rather than fabricated. It also discloses the return shape (document + web link), which annotations cannot convey. It stops short of describing validation failures or error 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?

Two dense sentences with no filler; the input requirement and output are front-loaded, followed by the side-effect and symbol-preservation constraints. Every clause carries information, though the phrasing is terse enough that some clauses need unpacking.

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 schema with no output schema, the description covers the essential contract: what to pass, what is produced, and that no persistent state is involved. Given the complexity of the nested SceneSpec, a brief note on validation/error reporting would have made it fully self-sufficient.

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 compensate for the two parameters. It meaningfully constrains `spec` ('complete SceneSpec', relative-relationship based, unknown values kept symbolic) but says nothing about the optional `name` parameter, so compensation is only partial.

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 pair and resource: generate and check a scene from a complete SceneSpec, and names the outputs (document plus a small-scene web link). It is clear what the tool does, though it never distinguishes itself from neighbors like preview_scene or export_scene, which also produce scene artifacts.

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 only implied: '传入完整 SceneSpec' signals the prerequisite that a fully-formed spec must already exist (presumably from get_build_spec), but there is no explicit when-to-use versus preview_scene/review_scene, and no statement of 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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so '不改变输入' merely repeats structured data and earns no credit. What the description does add is the scope of the check (inventory, contacts, track connections, orientation) and that findings are returned as concrete issues, but it says nothing about output format, error reporting, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence: input first, then what is checked, then what is returned, then the non-mutation guarantee. Zero filler and well 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?

For a read-only validator with no output schema, the description covers input, checked dimensions, result shape in outline, and side-effect behavior. The only gap is what '具体问题' actually looks like, but that is minor for a review tool whose annotations already establish safety.

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%, and the bare 'document' object carries no schema description, so '传入完整文档' usefully clarifies that a full document (not a partial one) is expected and that 'intent' is optional. Still, the description adds no detail on intent sub-fields beyond what the intent schema already documents, 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 names a specific verb (核对/检查) and enumerates the resources checked: 组件清单、接触、轨道连接和方向, plus the return (具体问题). It is clearly distinguishable from build_scene/export_scene, but it does not differentiate itself from the closest sibling, inspect_scene, so an agent still has to infer which inspection tool 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?

Passing the '完整文档' implies you should call this once you have a full scene document, and '可选几何意图' signals intent is optional. However, there is no explicit when-to-use or when-not-to-use guidance, and no sibling (e.g. inspect_scene, analyze_motion) is named as an alternative.

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

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.