opentakeoff-mcp

Overview Schema Source Related Servers Discussions Admin

list_shapes

Retrieve committed shape IDs and details—sheet, condition, role, quantities, room label, vertex count, and review state—then filter by sheet or condition without exporting the full takeoff.

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.

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_shapes"
  }
}

Input Schema

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

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.1.31Nov 7, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedOutput schema / properties / count / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / count / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / shapes / items / properties / agent_edits / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / shapes / items / properties / agent_edits / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / shapes / items / properties / nverts / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / shapes / items / properties / nverts / minimum
```
Added value: +-9007199254740991
```

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.3/5.0

Behavior4/5

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

With no annotations, the description still carries the behavioral load: it declares this a 'compact read', clarifies that filters narrow rather than error, and that an empty list is a valid result rather than a failure. It does not cover permissions, ordering, or result-size limits, which are the remaining behavioral gaps for a listing 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?

Two sentences, front-loaded with the inventory contents and followed by filtering semantics; almost every clause earns its place. The internal ticket reference '(#149)' is noise that costs a small amount of attention without helping an agent decide or invoke.

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 is simple (2 optional params) and has an output schema, so return values need not be detailed — yet the description helpfully enumerates the fields anyway. Combined with the empty-result and filter-combination notes, an agent has enough to call it correctly; only edge cases like ordering or very large result sets are unaddressed.

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 real meaning beyond the schema: the two filters can be combined ('by sheet, by condition, or both'), they narrow rather than fail, and a zero-match result is not an error. That combination and empty-result semantics are not expressed in the parameter descriptions.

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?

The description names a specific resource and scope ('every committed shape's id, sheet, condition tag, role, quantities, room label, vertex count, and review state') and explicitly positions itself against siblings: edit_shape and delete_shape consume these ids, and export_takeoff is the heavier alternative. An agent can distinguish list_shapes from export_takeoff and from the mutation tools without opening any 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?

It states the use case (mid-session lookup of a shape id to feed edit_shape/delete_shape) and the alternative it avoids (pulling the full export_takeoff payload), plus how to narrow with sheet and/or condition. What is missing is an explicit when-not-to-use case, e.g. that it only covers committed shapes and not in-progress measurements.

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

Deploy Server