opentakeoff-mcp

Overview Schema Source Related Servers Discussions Admin

set_scale

Define a sheet's drawing scale by label, feet per pixel, two-point calibration, or the detected note. Applies the scale explicitly and recomputes measurements and cutout quantities.

Instructions

Set a sheet's scale — exactly ONE of: label (a standard scale, e.g. '1/4" = 1'-0"'), upp (real feet per image px), calibrate (two points along a known dimension plus its real feet), or use_detected (adopt the drawn scale note read off the sheet). The detected scale is never applied automatically — setting it is always this explicit call. Changing an existing scale recomputes measurements and cutout restore quantities from geometry and records one undo_last step. Counts are unchanged. Human-reviewed dimensional work must be recalibrated in the canvas; scales must be finite and positive. Coordinates are image px at render scale 2.0: PDF pt × 2, origin top-left, y down (the browser canvas's native space). Sheet payloads carry dims in both px and pt.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "sheet": "<sheet>"
    },
    "name": "set_scale"
  }
}

Input Schema

Name	Required	Description
`upp`	No	Real feet per image px at render scale 2.0
`label`	No	A standard scale label, exactly as listed in the error on a miss
`sheet`	Yes
`calibrate`	No	Two points (image px) a known real distance apart, and that distance in feet
`use_detected`	No	true = adopt the sheet's detected scale

Output Schema

Name	Required	Description
`upp`	Yes	Real feet per image px at render scale 2.0
`label`	No	The standard scale label, when set by label or detected note
`sheet`	Yes
`source`	Yes
`warning`	No	Present when the sheet carries MULTIPLE distinct scale notes (#153) — enlarged plans/details likely; region measurements under a disagreeing note will warn
`confirmed`	Yes	Always false here: set_scale is the agent surface, and an agent-set scale stays UNCONFIRMED until a human confirms it in the canvas — quantities still flow, wearing the caveat

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.1.31Nov 7, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / calibrate / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / calibrate / properties / p1 / additionalItems
```
Added value: +false
```
- removedInput schema / properties / calibrate / properties / p2 / $ref
```
Removed value: -"#/properties/calibrate/properties/p1"
```
- addedInput schema / properties / calibrate / properties / p2 / additionalItems
```
Added value: +false
```
- addedInput schema / properties / calibrate / properties / p2 / items
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "number"
+  }
+]
```
- addedInput schema / properties / calibrate / properties / p2 / maxItems
```
Added value: +2
```
- addedInput schema / properties / calibrate / properties / p2 / minItems
```
Added value: +2
```
- addedInput schema / properties / calibrate / properties / p2 / type
```
Added value: +"array"
```

Changed2 schema fields changedv0.1.16Aug 12, 2026

addedOutput schema / properties / confirmed

Added value: +{
+  "description": "Always false here: set_scale is the agent surface, and an agent-set scale stays UNCONFIRMED until a human confirms it in the canvas — quantities still flow, wearing the caveat",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "sheet",
-  "upp",
-  "source"
-]New value: +[
+  "sheet",
+  "upp",
+  "source",
+  "confirmed"
+]

Changed1 schema field changedv0.1.9Jul 31, 2026

addedOutput schema / properties / warning

Added value: +{
+  "description": "Present when the sheet carries MULTIPLE distinct scale notes (#153) — enlarged plans/details likely; region measurements under a disagreeing note will warn",
+  "type": "string"
+}

Addedv0.1.4Jul 21, 2026
Removedv0.1.3Jul 21, 2026
Addedv0.1.2Jul 17, 2026
Removedv0.1.1Jul 17, 2026
First observedJul 15, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the side effects (measurements and cutout restore quantities recomputed from geometry), that exactly one undo_last step is recorded, that counts are unchanged, and the validation constraints (finite, positive). This is the kind of mutation-profile information an agent needs before calling a write tool.

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

Conciseness4/5

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

Front-loaded with the mode enumeration, then side effects, then coordinate conventions — a sensible order. The coordinate paragraph is dense but load-bearing for the calibrate mode; a minor amount of restatement exists between the prose and the schema's own parameter descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and side effects, undo behavior, and validation are all covered. The one gap is the required `sheet` parameter, which has no description anywhere — the agent is not told whether it expects a sheet id, name, or path.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the baseline is 3; the description adds real meaning on top by giving a concrete label example, defining upp as real feet per image px, explaining calibrate as two points along a known dimension, and defining use_detected as adopting the drawn note. The coordinate-space paragraph (render scale 2.0, PDF pt × 2, origin top-left, y down) is essential for constructing p1/p2 correctly and is not in the schema.

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

Purpose5/5

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

Opens with a specific verb+resource ("Set a sheet's scale") and immediately enumerates the four mutually exclusive input modes (label, upp, calibrate, use_detected), each with a concrete gloss. No sibling tool sets scale, and the description makes the operation unmistakable 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the hard selection rule ("exactly ONE of") and clarifies that detected scale is never auto-applied, so adopting it requires this explicit call — a genuine when-to-use signal. It also routes human-reviewed dimensional work to the canvas recalibration path. It does not, however, spell out which mode an agent should prefer in ambiguous cases (e.g. label vs upp).

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

Deploy Server