opentakeoff-mcp

Overview Schema Source Related Servers Discussions Admin

list_annotations

Fetch all takeoff annotations with condition IDs resolved to finish tags. Filter by sheet, condition, or both; includes verdicts and unattached notes.

Instructions

Every annotation on the takeoff, with condition_id RESOLVED to its finish tag so you can act on the reply without joining against conditions[]. Filter by sheet, by condition, or both. Coordinates come back in image px (the same frame you passed in), not the normalized form they're stored as. unattached counts the notes carrying no condition — the candidates for link_annotation. verdicts is the approval family's inventory (mark_verdict/delete_verdict): every mark with its actor stated — the estimator's APPROVED ring or the agent's AGENT diamond — under the same filters, a condition filter reaching a verdict through its target shape. 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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sheet`	No	Only annotations on this sheet
`condition`	No	Only annotations attached to this finish tag

Output Schema

TableJSON Schema

Name	Required	Description
`count`	Yes
`verdicts`	Yes	Approval-family records (#176) under the same filters: sheet applies directly; a condition filter reaches a verdict THROUGH its target shape (a sheet-point mark carries no scope and drops out)
`unattached`	Yes	How many carry no condition — candidates for link_annotation
`annotations`	Yes
`verdict_count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.26Oct 1, 2026

addedOutput schema / properties / annotations / items / properties / text_resolved

Added value: +{
+  "description": "Only when text carries a {{qty}} field: the note as the sheet shows it, {{qty}} filled with the linked condition's measured quantity (multiplier applied, no waste)",
+  "type": "string"
+}

addedOutput schema / properties / annotations / items / properties / unresolved_fields

Added value: +{
+  "description": "Fields that could not fill (no linked condition, nothing measured yet, or an unknown name) — they stay literal and print in the warning ink; link_annotation fixes the first case",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed3 schema fields changedv0.1.12Aug 3, 2026

addedOutput schema / properties / verdict_count
```
Added value: +{
+  "type": "integer"
+}
```

addedOutput schema / properties / verdicts

Added value: +{
+  "description": "Approval-family records (#176) under the same filters: sheet applies directly; a condition filter reaches a verdict THROUGH its target shape (a sheet-point mark carries no scope and drops out)",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "actor": {
+        "description": "\"estimator\" = the human APPROVED ring (ink — import-borne here, never minted over MCP), \"agent\" = the AGENT diamond",
+        "enum": [
+          "estimator",
+          "agent"
+        ],
+        "type": "string"
+      },
+      "at": {
+        "description": "Render anchor (image px) — absent only when the record rides a sheet from a file this session hasn't loaded (#152)",
+        "items": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "number"
+          }
+        ],
+        "maxItems": 2,
+        "minItems": 2,
+        "type": "array"
+      },
+      "condition": {
+        "description": "The targeted shape's finish tag, resolved — '' for sheet-point marks",
+        "type": "string"
+      },
+      "id": {
+        "type": "string"
+      },
+      "shape_id": {
+        "description": "Present when the verdict targets a committed shape — WHAT was marked, not where it draws",
+        "type": "string"
+      },
+      "sheet": {
+        "type": "string"
+      },
+      "text": {
+        "description": "The optional short note riding the record",
+        "type": "string"
+      },
+      "ts": {
+        "description": "ISO-8601 mint time",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "actor",
+      "sheet",
+      "condition"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "annotations",
-  "count",
-  "unattached"
-]New value: +[
+  "annotations",
+  "count",
+  "unattached",
+  "verdicts",
+  "verdict_count"
+]

Changed3 schema fields changedv0.1.11Aug 2, 2026

changedOutput schema / properties / annotations / items / properties / from / description

Previous value: -"Arrow tail (image px)"New value: +"Arrow tail / dimension start (image px)"

addedOutput schema / properties / annotations / items / properties / length_lf

Added value: +{
+  "description": "Dimension only: the measured length in real feet, snapshotted at annotate time from the sheet scale",
+  "type": "number"
+}

changedOutput schema / properties / annotations / items / properties / to / description

Previous value: -"Arrow head (image px)"New value: +"Arrow head / dimension end (image px)"

Changed3 schema fields changedv0.1.9Jul 31, 2026

addedOutput schema / properties / annotations / items / properties / from

Added value: +{
+  "description": "Arrow tail (image px)",
+  "items": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "number"
+    }
+  ],
+  "maxItems": 2,
+  "minItems": 2,
+  "type": "array"
+}

addedOutput schema / properties / annotations / items / properties / r

Added value: +{
+  "description": "Bubble radius (image px)",
+  "type": "number"
+}

addedOutput schema / properties / annotations / items / properties / to

Added value: +{
+  "description": "Arrow head (image px)",
+  "items": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "number"
+    }
+  ],
+  "maxItems": 2,
+  "minItems": 2,
+  "type": "array"
+}

Addedv0.1.6Jul 27, 2026

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden and delivers real behavioral context: the coordinate frame (image px at render scale 2.0, PDF pt × 2, origin top-left, y down), resolved condition IDs, and sheet dims in both px and pt. This is beyond what the schema reveals. The coordinate explanation is stated twice, but the substance is genuinely informative.

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

Conciseness3/5

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

The core purpose is front-loaded, but the paragraph is dense and repeats the coordinate frame twice ('Coordinates come back in image px' then 'Coordinates are image px at render scale 2.0'), which is redundant bulk. Several backtick terms pile up without structure, making it heavier than necessary.

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?

The tool has an output schema, so return shape needn't be explained, yet the description still supplies the coordinate frame and render-scale details an agent needs to interpret results correctly. Combined with filter behavior and verdict/unattached semantics, it is largely complete for a two-param read tool.

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 100% for both params, so the baseline is 3. The description adds meaning beyond the schema: a condition filter reaches a verdict through its target shape, and 'both' may be combined. Modest but real added value over the field descriptions.

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

Purpose4/5

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

States a specific verb (list) and resource (annotations on the takeoff) plus a distinguishing behavior: condition_id is RESOLVED to its finish tag. It even signals downstream consumers (link_annotation candidates, mark_verdict/delete_verdict inventory), which helps separate it from sibling listers like list_shapes. It never names a sibling as an explicit alternative, so it stops short of 5.

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?

Gives clear context: filter by sheet, by condition, or both, and notes `unattached` are the candidates for link_annotation while `verdicts` feeds mark_verdict/delete_verdict. That routes the agent toward follow-on tools. It lacks explicit when-not guidance, so 4 rather than 5.

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