opentakeoff-mcp

Overview Schema Source Related Servers Discussions Admin

list_shapes

List committed takeoff shapes with their ids, sheets, conditions, quantities, and review state; filter by sheet or condition to get the ids edit_shape and delete_shape require.

Instructions

The mid-session shape inventory (#149): every committed shape's id, sheet, condition tag, role, quantities, room label, vertex count, and review state in one compact read — the ids edit_shape and delete_shape assume you have, without pulling the whole export_takeoff payload to find one shape. Filter by sheet, by condition, or both; filters narrow, an empty list is a result, not an error.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sheet`	No	Only shapes on this sheet
`condition`	No	Only shapes under this finish tag (must exist)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	Yes
`shapes`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.1.21Sep 12, 2026

addedOutput schema / properties / shapes / items / properties / proposal_id

Added value: +{
+  "description": "The propose_takeoff batch this shape was committed under (#365) — present on shapes committed while a proposal was open; an accepted shape keeps it as history",
+  "type": "string"
+}

Changed1 schema field changedv0.1.14Aug 4, 2026

addedOutput schema / properties / shapes / items / properties / label

Added value: +{
+  "description": "The room (or phase/area) this shape belongs to — detect_rooms stamps the room number it traced from; edit_shape sets or clears it. Absent when unlabeled",
+  "type": "string"
+}

Changed1 schema field changedv0.1.10Aug 1, 2026

addedOutput schema / properties / shapes / items / properties / assignment

Added value: +{
+  "description": "Where the finish tag came from: \"schedule\" = resolved from the room's own schedule row, \"asserted\" = the agent chose it. origin.assignment in export_takeoff carries the citation. Absent on human canvas shapes",
+  "enum": [
+    "schedule",
+    "asserted"
+  ],
+  "type": "string"
+}

Addedv0.1.9Jul 31, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden and does disclose the key traits: read scope is limited to 'committed' shapes, filters only narrow (never broaden), and an empty result is normal rather than a failure. It does not cover auth/permission needs or pagination limits, which would be relevant for a large inventory read.

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 core purpose and field list, and the operational caveats come last. It is a single dense sentence with some incidental noise (the '#149' issue reference) but each clause largely earns its place.

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

Completeness5/5

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

For a two-param, optional-filter read whose output schema already defines the return payload, the description covers scope, filter behavior, and empty-result handling completely. Nothing needed to invoke it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters are already documented (sheet = 'Only shapes on this sheet', condition = 'Only shapes under this finish tag'). The description adds only the semantic that filters narrow rather than expand, which is useful but minimal beyond 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?

States a specific verb+resource ('shape inventory') and enumerates the exact fields returned (id, sheet, condition tag, role, quantities, room label, vertex count, review state). It explicitly distinguishes itself from sibling export_takeoff and positions itself as the id source that edit_shape and delete_shape require.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Names the alternative it replaces ('without pulling the whole export_takeoff payload'), states the filtering options (sheet, condition, or both), and clarifies result semantics ('filters narrow, an empty list is a result, not an error'). An agent knows exactly when to reach for this vs. the bulk export.

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