Skip to main content
Glama

propose_takeoff

Open a named proposal batch before committing shapes, so related takeoff measurements attach to one identity and the estimator accepts the whole batch with a single decision.

Instructions

Open a PROPOSAL — a named batch of the shapes you are about to commit, with one identity (#365). Every shape you commit from here on (measure_polygon, measure_line, measure_surface, place_count, the sweeps, the derives, cut_out) attaches to it until you open another proposal or withdraw this one; the estimator then sees ONE Accept pill for the whole batch instead of one per shape — a forty-room pass becomes one decision, not forty. Use it BEFORE the work, the way an estimator titles a takeoff before tracing: "Level 2 rooms per finish schedule A-601", "Base derived from CPT-1 rooms". label is what the estimator reads on the pill; rationale is what decided the batch (the schedule row, the sheet, the rule) — both required, neither is a comment. Nothing here commits geometry or changes a total: an empty proposal is just a heading. The batch is what revise_proposal replaces and withdraw_proposal removes; shapes the estimator has already accepted leave the batch and no agent verb reaches them. takeoff_summary carries the ledger (pending / accepted / withdrawn per batch).

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": {
      "label": "<label>",
      "rationale": "<rationale>"
    },
    "name": "propose_takeoff"
  }
}

Input Schema

NameRequiredDescriptionDefault
labelYesThe batch's title, as the estimator will read it on the Accept pill
rationaleYesWhat decided the batch — cite the schedule row, sheet, or rule

Output Schema

NameRequiredDescriptionDefault
noteYes
labelYes
rationaleYes
proposal_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.31
    • removedInput schema / additionalProperties
      Removed value: -false
  2. Addedv0.1.21

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so: it discloses that nothing is committed, that an empty proposal is only a heading, and — critically — that shapes already accepted by the estimator leave the batch and no agent verb can reach them. That is a real, non-obvious side effect an agent could otherwise trip over, and it is stated explicitly.

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?

The core action and its scope are front-loaded in the first sentence, and the rest is organized around lifecycle, then parameters, then return. A few rhetorical flourishes ("a forty-room pass becomes one decision, not forty") are slightly padded but do convey the motivating value of batching.

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?

An output schema exists, and the description still points to where the ledger lives (takeoff_summary, pending/accepted/withdrawn per batch), which is the one piece an agent needs to verify the proposal state. Combined with the lifecycle and non-commitment guarantees, nothing required to call it correctly is missing.

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 both parameters are already documented, and the description largely restates them (label = pill text, rationale = what decided the batch). It does add meaning beyond the schema by insisting both are required and "neither is a comment," pushing the agent toward substantively citing a schedule row or sheet rather than placeholder text.

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?

"Open a PROPOSAL — a named batch of the shapes you are about to commit, with one identity" gives a specific verb (open/create), a specific resource (proposal/batch), and the scope of what the object contains. It is immediately distinguishable from revise_proposal, withdraw_proposal, and takeoff_summary, which are described as the replace/remove/read counterparts.

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?

"Use it BEFORE the work, the way an estimator titles a takeoff before tracing" fixes the ordering relative to the measurement verbs, and the description enumerates which siblings attach to the proposal (measure_polygon, measure_line, place_count, cut_out, sweeps, derives). It also states the lifecycle boundaries: a proposal stays open until another is opened or this one is withdrawn, revise_proposal replaces the batch, and withdraw_proposal removes it.

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