opentakeoff-mcp

Overview Schema Source Related Servers Discussions Admin

list_annotations

Retrieve all takeoff annotations with finish tags resolved, filter them by sheet or condition, and review unattached notes plus approval verdicts in image-pixel coordinates.

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_annotations"
  }
}

Input Schema

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

Output 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.

Changed18 schema fields changedv0.1.31Nov 7, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedOutput schema / properties / annotations / items / properties / at / additionalItems
```
Added value: +false
```
- addedOutput schema / properties / annotations / items / properties / from / additionalItems
```
Added value: +false
```
- addedOutput schema / properties / annotations / items / properties / rect / items / additionalItems
```
Added value: +false
```
- removedOutput schema / properties / annotations / items / properties / rect / items / anyOf
```
Removed value: -[
-  {
-    "not": {}
-  },
-  {
-    "items": [
-      {
-        "type": "number"
-      },
-      {
-        "type": "number"
-      }
-    ],
-    "maxItems": 2,
-    "minItems": 2,
-    "type": "array"
-  }
-]
```
- addedOutput schema / properties / annotations / items / properties / rect / items / items
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "number"
+  }
+]
```
- addedOutput schema / properties / annotations / items / properties / rect / items / maxItems
```
Added value: +2
```
- addedOutput schema / properties / annotations / items / properties / rect / items / minItems
```
Added value: +2
```
- addedOutput schema / properties / annotations / items / properties / rect / items / type
```
Added value: +"array"
```
- addedOutput schema / properties / annotations / items / properties / target / additionalItems
```
Added value: +false
```
- addedOutput schema / properties / annotations / items / properties / to / additionalItems
```
Added value: +false
```
- addedOutput schema / properties / count / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / count / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / unattached / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / unattached / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / verdict_count / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / verdict_count / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / verdicts / items / properties / at / additionalItems
```
Added value: +false
```

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

A4.3/5.0

Behavior4/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 substantial work: it discloses that condition resolution happens server-side, that coordinates are returned in image px at render scale 2.0 (PDF pt × 2, origin top-left, y down), and that sheet payloads carry dims in both px and pt. It never explicitly states read-only/no-side-effects, and says nothing about limits or pagination, which are the remaining gaps.

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 most important fact (condition_id is resolved), then filters, then coordinate frame, then payload inventory. Dense but mostly earning its place; the verdict explanation ("the estimator's APPROVED ring or the agent's AGENT diamond") and the duplicated coordinate sentence (mentioned twice) add some redundancy.

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, yet the description still explains the return payload ("unattached" count, "verdicts" inventory), which is genuinely useful for planning follow-ups. For a two-param, read-oriented tool this is close to complete; only the absence of an explicit read-only statement and any pagination/volume expectation keeps it from a 5.

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%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that the two filters can be combined, and that a condition filter reaches verdicts "through its target shape" — a non-obvious semantic. It also clarifies that the condition parameter matches against the resolved finish tag rather than a raw condition_id.

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?

Names a specific verb and resource ("Every annotation on the takeoff") and immediately states the key transformation — condition_id RESOLVED to its finish tag — which distinguishes it from raw listing tools. It also routes follow-up actions to named siblings (link_annotation for unattached notes, mark_verdict/delete_verdict for verdicts), so an agent can tell it apart from list_shapes or count_marks.

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?

Explicitly states the filtering modes ("Filter by sheet, by condition, or both") and gives a usage motive ("so you can act on the reply without joining against conditions[]"). What's missing is an explicit exclusion — nothing says when to prefer list_shapes, count_marks, or sheet_context instead.

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

Deploy Server