Skip to main content
Glama

CutOptim Engine

Optimize 1D bars

optimize_1d

Metered: one Engine API call. Cut lengths from bars, tubes, profiles or rolls and get the cutting pattern per bar. 1D / linear optimization (bars, profiles, tube). Cut parts of a given length from stock bars. Returns the rods used, the position of every part along each rod, the leftover length and the yield metrics.

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": {
      "parts": "<parts>",
      "stock": "<stock>"
    },
    "name": "optimize_1d"
  }
}

Input Schema

NameRequiredDescriptionDefault
asyncNoOpt in to answers that may arrive later. With `"auto"` a job that finishes within the synchronous time limit still answers 200 with the plan, exactly as without it; a job that would outgrow the limit answers **202** with a `jobId` instead, keeps solving, and its plan is read with `GET /v1/jobs/{id}` (the same poll as engine `max`). The call is billed once, when the plan is written; a solve that fails is not billed. Without this field such a job answers 504 `solve_timeout` with the `jobId` in `details` and is not charged. The official SDKs send it and wait for the job for you.
partsYesThe lengths to cut, one row per part type (`length`, optional `qty`, `name`, mitred `ends`).
stockYesThe bar lengths to cut from, one row per length (`length`, optional `qty`, `price`).
engineNo`max` is not offered here: it is a 2D (and, separately, nesting) tier, and `engine: "max"` on this path is a **400** before a call is charged. In 1D `balanced` resolves to the same packer as `heuristic` — the linear packer is already a best-of-multiple-strategies search, so there is no separate balanced mode. The value is accepted and echoed back so a single client can send one engine id for both endpoints.heuristic
includeNoThree kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: "include"`. Export and data tokens do not affect narrowing, so `["svg"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `["cutPlan","offcuts","svg"]` to keep everything.
optionsNoThe 1D option set is deliberately smaller: there is no `firstCut`, `maxCutStages` or `minimizeRotations`, because none of them means anything on a bar.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / async
      Added value: +{
      +  "description": "Opt in to answers that may arrive later. With `\"auto\"` a job that finishes within the synchronous time limit still answers 200 with the plan, exactly as without it; a job that would outgrow the limit answers **202** with a `jobId` instead, keeps solving, and its plan is read with `GET /v1/jobs/{id}` (the same poll as engine `max`). The call is billed once, when the plan is written; a solve that fails is not billed. Without this field such a job answers 504 `solve_timeout` with the `jobId` in `details` and is not charged. The official SDKs send it and wait for the job for you.",
      +  "enum": [
      +    "auto"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "properties": {
      +      "contractVersion": {
      +        "type": "string"
      +      },
      +      "csv": {
      +        "type": "string"
      +      },
      +      "cutPlan": {
      +        "items": {
      +          "properties": {
      +            "angle": {
      +              "type": "number"
      +            },
      +            "axis": {
      +              "enum": [
      +                "h",
      +                "v"
      +              ],
      +              "type": "string"
      +            },
      +            "bevel": {
      +              "type": "number"
      +            },
      +            "length": {
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "pos": {
      +              "type": "number"
      +            },
      +            "sheet": {
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            "stage": {
      +              "minimum": 1,
      +              "type": "integer"
      +            },
      +            "step": {
      +              "minimum": 1,
      +              "type": "integer"
      +            }
      +          },
      +          "required": [
      +            "sheet",
      +            "step",
      +            "axis",
      +            "pos",
      +            "length",
      +            "stage"
      +          ],
      +          "type": "object"
      +        },
      +        "type": [
      +          "array",
      +          "null"
      +        ]
      +      },
      +      "deterministic": {
      +        "const": true,
      +        "type": "boolean"
      +      },
      +      "dxf": {
      +        "type": "string"
      +      },
      +      "engine": {
      +        "enum": [
      +          "heuristic",
      +          "balanced"
      +        ],
      +        "type": "string"
      +      },
      +      "engineVersion": {
      +        "type": "string"
      +      },
      +      "materials": {
      +        "items": {
      +          "properties": {
      +            "material": {
      +              "type": "string"
      +            },
      +            "placed": {
      +              "type": "integer"
      +            },
      +            "rodCount": {
      +              "type": "integer"
      +            },
      +            "total": {
      +              "type": "integer"
      +            },
      +            "totalPrice": {
      +              "type": "number"
      +            },
      +            "yieldPct": {
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "material",
      +            "rodCount",
      +            "yieldPct",
      +            "placed",
      +            "total",
      +            "totalPrice"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "metrics": {
      +        "properties": {
      +          "cuts": {
      +            "type": "integer"
      +          },
      +          "placed": {
      +            "type": "integer"
      +          },
      +          "rodCount": {
      +            "type": "integer"
      +          },
      +          "sharedCuts": {
      +            "type": "integer"
      +          },
      +          "toleranceAcceptedCount": {
      +            "type": "integer"
      +          },
      +          "total": {
      +            "type": "integer"
      +          },
      +          "totalPrice": {
      +            "type": "number"
      +          },
      +          "yieldPct": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "rodCount",
      +          "yieldPct",
      +          "placed",
      +          "total",
      +          "cuts",
      +          "totalPrice",
      +          "toleranceAcceptedCount"
      +        ],
      +        "type": "object"
      +      },
      +      "rods": {
      +        "items": {
      +          "properties": {
      +            "length": {
      +              "type": "number"
      +            },
      +            "material": {
      +              "type": "string"
      +            },
      +            "meta": {
      +              "type": "object"
      +            },
      +            "offcuts": {
      +              "items": {
      +                "type": "number"
      +              },
      +              "type": "array"
      +            },
      +            "parts": {
      +              "items": {
      +                "properties": {
      +                  "flipped": {
      +                    "enum": [
      +                      "face",
      +                      "edge",
      +                      "roll"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "length": {
      +                    "type": "number"
      +                  },
      +                  "meta": {
      +                    "type": "object"
      +                  },
      +                  "name": {
      +                    "type": "string"
      +                  },
      +                  "pos": {
      +                    "type": "number"
      +                  },
      +                  "sharedCut": {
      +                    "properties": {
      +                      "angle": {
      +                        "type": "number"
      +                      },
      +                      "bevel": {
      +                        "type": "number"
      +                      },
      +                      "kerfAlongAxis": {
      +                        "type": "number"
      +                      },
      +                      "lead": {
      +                        "type": "number"
      +                      }
      +                    },
      +                    "required": [
      +                      "angle",
      +                      "bevel",
      +                      "kerfAlongAxis",
      +                      "lead"
      +                    ],
      +                    "type": "object"
      +                  }
      +                },
      +                "required": [
      +                  "name",
      +                  "pos",
      +                  "length"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "price": {
      +              "type": [
      +                "number",
      +                "null"
      +              ]
      +            },
      +            "remaining": {
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "length",
      +            "price",
      +            "remaining",
      +            "parts"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "timing": {
      +        "properties": {
      +          "solveMs": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "solveMs"
      +        ],
      +        "type": "object"
      +      },
      +      "unmatchedMaterials": {
      +        "items": {
      +          "properties": {
      +            "material": {
      +              "type": "string"
      +            },
      +            "parts": {
      +              "items": {
      +                "properties": {
      +                  "length": {
      +                    "type": "number"
      +                  },
      +                  "name": {
      +                    "type": "string"
      +                  },
      +                  "qty": {
      +                    "minimum": 1,
      +                    "type": "integer"
      +                  }
      +                },
      +                "required": [
      +                  "name",
      +                  "length",
      +                  "qty"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            }
      +          },
      +          "required": [
      +            "material",
      +            "parts"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "unplaced": {
      +        "items": {
      +          "properties": {
      +            "length": {
      +              "type": "number"
      +            },
      +            "name": {
      +              "type": "string"
      +            },
      +            "qty": {
      +              "minimum": 1,
      +              "type": "integer"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "length",
      +            "qty"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "warnings": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "engine",
      +      "engineVersion",
      +      "contractVersion",
      +      "deterministic",
      +      "rods",
      +      "metrics",
      +      "unplaced",
      +      "warnings",
      +      "timing"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "engine": {
      +        "enum": [
      +          "heuristic",
      +          "balanced"
      +        ],
      +        "type": "string"
      +      },
      +      "jobId": {
      +        "format": "uuid",
      +        "type": "string"
      +      },
      +      "mode": {
      +        "enum": [
      +          "1d"
      +        ],
      +        "type": "string"
      +      },
      +      "pollAfterMs": {
      +        "type": "integer"
      +      },
      +      "quota": {
      +        "properties": {
      +          "limit": {
      +            "type": "integer"
      +          },
      +          "reserved": {
      +            "type": "integer"
      +          },
      +          "used": {
      +            "type": "integer"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "status": {
      +        "enum": [
      +          "running"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "jobId",
      +      "status",
      +      "mode",
      +      "engine",
      +      "pollAfterMs"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedOutput schema / properties
      Removed value: -{
      -  "contractVersion": {
      -    "type": "string"
      -  },
      -  "csv": {
      -    "type": "string"
      -  },
      -  "cutPlan": {
      -    "items": {
      -      "properties": {
      -        "angle": {
      -          "type": "number"
      -        },
      -        "axis": {
      -          "enum": [
      -            "h",
      -            "v"
      -          ],
      -          "type": "string"
      -        },
      -        "bevel": {
      -          "type": "number"
      -        },
      -        "length": {
      -          "minimum": 0,
      -          "type": "number"
      -        },
      -        "pos": {
      -          "type": "number"
      -        },
      -        "sheet": {
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "stage": {
      -          "minimum": 1,
      -          "type": "integer"
      -        },
      -        "step": {
      -          "minimum": 1,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "sheet",
      -        "step",
      -        "axis",
      -        "pos",
      -        "length",
      -        "stage"
      -      ],
      -      "type": "object"
      -    },
      -    "type": [
      -      "array",
      -      "null"
      -    ]
      -  },
      -  "deterministic": {
      -    "const": true,
      -    "type": "boolean"
      -  },
      -  "dxf": {
      -    "type": "string"
      -  },
      -  "engine": {
      -    "enum": [
      -      "heuristic",
      -      "balanced"
      -    ],
      -    "type": "string"
      -  },
      -  "engineVersion": {
      -    "type": "string"
      -  },
      -  "materials": {
      -    "items": {
      -      "properties": {
      -        "material": {
      -          "type": "string"
      -        },
      -        "placed": {
      -          "type": "integer"
      -        },
      -        "rodCount": {
      -          "type": "integer"
      -        },
      -        "total": {
      -          "type": "integer"
      -        },
      -        "totalPrice": {
      -          "type": "number"
      -        },
      -        "yieldPct": {
      -          "type": "number"
      -        }
      -      },
      -      "required": [
      -        "material",
      -        "rodCount",
      -        "yieldPct",
      -        "placed",
      -        "total",
      -        "totalPrice"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "metrics": {
      -    "properties": {
      -      "cuts": {
      -        "type": "integer"
      -      },
      -      "placed": {
      -        "type": "integer"
      -      },
      -      "rodCount": {
      -        "type": "integer"
      -      },
      -      "sharedCuts": {
      -        "type": "integer"
      -      },
      -      "toleranceAcceptedCount": {
      -        "type": "integer"
      -      },
      -      "total": {
      -        "type": "integer"
      -      },
      -      "totalPrice": {
      -        "type": "number"
      -      },
      -      "yieldPct": {
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "rodCount",
      -      "yieldPct",
      -      "placed",
      -      "total",
      -      "cuts",
      -      "totalPrice",
      -      "toleranceAcceptedCount"
      -    ],
      -    "type": "object"
      -  },
      -  "rods": {
      -    "items": {
      -      "properties": {
      -        "length": {
      -          "type": "number"
      -        },
      -        "material": {
      -          "type": "string"
      -        },
      -        "meta": {
      -          "type": "object"
      -        },
      -        "offcuts": {
      -          "items": {
      -            "type": "number"
      -          },
      -          "type": "array"
      -        },
      -        "parts": {
      -          "items": {
      -            "properties": {
      -              "flipped": {
      -                "enum": [
      -                  "face",
      -                  "edge",
      -                  "roll"
      -                ],
      -                "type": "string"
      -              },
      -              "length": {
      -                "type": "number"
      -              },
      -              "meta": {
      -                "type": "object"
      -              },
      -              "name": {
      -                "type": "string"
      -              },
      -              "pos": {
      -                "type": "number"
      -              },
      -              "sharedCut": {
      -                "properties": {
      -                  "angle": {
      -                    "type": "number"
      -                  },
      -                  "bevel": {
      -                    "type": "number"
      -                  },
      -                  "kerfAlongAxis": {
      -                    "type": "number"
      -                  },
      -                  "lead": {
      -                    "type": "number"
      -                  }
      -                },
      -                "required": [
      -                  "angle",
      -                  "bevel",
      -                  "kerfAlongAxis",
      -                  "lead"
      -                ],
      -                "type": "object"
      -              }
      -            },
      -            "required": [
      -              "name",
      -              "pos",
      -              "length"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        "price": {
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "remaining": {
      -          "type": "number"
      -        }
      -      },
      -      "required": [
      -        "length",
      -        "price",
      -        "remaining",
      -        "parts"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "timing": {
      -    "properties": {
      -      "solveMs": {
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "solveMs"
      -    ],
      -    "type": "object"
      -  },
      -  "unmatchedMaterials": {
      -    "items": {
      -      "properties": {
      -        "material": {
      -          "type": "string"
      -        },
      -        "parts": {
      -          "items": {
      -            "properties": {
      -              "length": {
      -                "type": "number"
      -              },
      -              "name": {
      -                "type": "string"
      -              },
      -              "qty": {
      -                "minimum": 1,
      -                "type": "integer"
      -              }
      -            },
      -            "required": [
      -              "name",
      -              "length",
      -              "qty"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        }
      -      },
      -      "required": [
      -        "material",
      -        "parts"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "unplaced": {
      -    "items": {
      -      "properties": {
      -        "length": {
      -          "type": "number"
      -        },
      -        "name": {
      -          "type": "string"
      -        },
      -        "qty": {
      -          "minimum": 1,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "name",
      -        "length",
      -        "qty"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "warnings": {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  }
      -}
    • removedOutput schema / required
      Removed value: -[
      -  "engine",
      -  "engineVersion",
      -  "contractVersion",
      -  "deterministic",
      -  "rods",
      -  "metrics",
      -  "unplaced",
      -  "warnings",
      -  "timing"
      -]
  2. Changed2 schema fields changed
    • addedInput schema / properties / parts / description
      Added value: +"The lengths to cut, one row per part type (`length`, optional `qty`, `name`, mitred `ends`)."
    • addedInput schema / properties / stock / description
      Added value: +"The bar lengths to cut from, one row per length (`length`, optional `qty`, `price`)."
  3. Changed10 schema fields changed
    • addedInput schema / properties / options / properties / mitrePairing
      Added value: +{
      +  "default": false,
      +  "description": "Pair parts of one section whose facing ends (`parts[].ends`) can share ONE saw cut. Off by default: a request without it is solved exactly as before. On, a plan with pairs is returned only when it ranks strictly better than the unpaired plan by the packer's own ranking (parts placed first, then material — or price with `minimizeCost`); otherwise the unpaired plan comes back. Pairs only, no chains of three or more.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / parts / items / properties / depth
      Added value: +{
      +  "description": "Mitre pairing only: the side of the bar the `angle` of `ends` is seen on. Required with `ends` (a 1D part has no cross-section to take it from). Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side.",
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / parts / items / properties / ends
      Added value: +{
      +  "description": "The angled ends of a part, read only with `options.mitrePairing`. Two parts of one section whose facing ends lie in one plane (after a turn `flip` allows) can be cut with ONE saw cut between them: the triangle between the long and the short point is not wasted. Without `mitrePairing` the ends are not used (a warning says so) and the part packs as its `length`.",
      +  "properties": {
      +    "end": {
      +      "description": "One end cut of a part, in degrees from square (0 = a square end), signed. The part is measured long point to long point (`length` is its overall length). A part whose two end cuts would cross inside its section (shorter than its leads) cannot be made: a 400 `invalid_request` naming `parts[i].ends` says how long it must at least be.",
      +      "properties": {
      +        "angle": {
      +          "description": "The face angle: the mitre or plumb cut as seen on the `depth` side (wood: on `sh` as entered).",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        },
      +        "bevel": {
      +          "default": 0,
      +          "description": "The edge angle: the bevel as seen on the `thickness` side (wood: on `sw` as entered). A compound cut has both.",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "angle"
      +      ],
      +      "type": "object"
      +    },
      +    "start": {
      +      "description": "One end cut of a part, in degrees from square (0 = a square end), signed. The part is measured long point to long point (`length` is its overall length). A part whose two end cuts would cross inside its section (shorter than its leads) cannot be made: a 400 `invalid_request` naming `parts[i].ends` says how long it must at least be.",
      +      "properties": {
      +        "angle": {
      +          "description": "The face angle: the mitre or plumb cut as seen on the `depth` side (wood: on `sh` as entered).",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        },
      +        "bevel": {
      +          "default": 0,
      +          "description": "The edge angle: the bevel as seen on the `thickness` side (wood: on `sw` as entered). A compound cut has both.",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "angle"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / parts / items / properties / flip
      Added value: +{
      +  "default": "none",
      +  "description": "Mitre pairing only: which 180° turns of the part on the bar are allowed, so its angled end can meet a neighbour's. `none` (default — a profiled moulding or one-sided stock), `face` (end for end, the crown or top edge stays up — roof members), `edge` (end for end over the edge — flat stock, frames), `any`.",
      +  "enum": [
      +    "none",
      +    "face",
      +    "edge",
      +    "any"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / parts / items / properties / thickness
      Added value: +{
      +  "description": "Mitre pairing only: the other side, the one the `bevel` is seen on. Required with `ends`. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side.",
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
    • addedOutput schema / properties / cutPlan / items / properties / angle
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / cutPlan / items / properties / bevel
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / metrics / properties / sharedCuts
      Added value: +{
      +  "type": "integer"
      +}
    • addedOutput schema / properties / rods / items / properties / parts / items / properties / flipped
      Added value: +{
      +  "enum": [
      +    "face",
      +    "edge",
      +    "roll"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / rods / items / properties / parts / items / properties / sharedCut
      Added value: +{
      +  "properties": {
      +    "angle": {
      +      "type": "number"
      +    },
      +    "bevel": {
      +      "type": "number"
      +    },
      +    "kerfAlongAxis": {
      +      "type": "number"
      +    },
      +    "lead": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "angle",
      +    "bevel",
      +    "kerfAlongAxis",
      +    "lead"
      +  ],
      +  "type": "object"
      +}
  4. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Adds genuinely useful context beyond the annotations: the call is metered/billed as one Engine API call, and it states what comes back (rods used, part positions, leftover length, yield metrics). It does not repeat the annotation flags and does not contradict them (a solve that writes a plan is consistent with readOnlyHint=false, destructiveHint=false). It stops short of explaining the async/202 path or failure billing, which live only in the schema.

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?

Short and front-loaded, with the metering warning first and the outcome list last. The third sentence ('Cut parts of a given length from stock bars') largely restates the opening sentence, which is the only real waste.

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?

Output schema exists, so the description does not need to enumerate return fields, yet it still summarizes them. For a nested, option-rich 1D packer the description covers purpose and result shape adequately; the only gap is the absence of any pointer to validate_1d or the async job flow when calling it cold.

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 every parameter (parts, stock, engine, include, options, async) is already documented in detail and the codebase schema carries the heavy lifting. The description adds no parameter-level meaning beyond restating that lengths come from parts and bars from stock, so the baseline 3 applies.

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 ('Cut lengths from bars, tubes, profiles or rolls', '1D / linear optimization') and the scope word '1D / linear' cleanly separates it from the 2D, nesting and wood siblings without needing their names. An agent can tell what domain this covers from the first two sentences.

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

Usage Guidelines3/5

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

Usage is implied by the domain scope (cutting stock bars into parts), but there is no explicit when-to-use statement, no mention of the validate_1d sibling as a pre-check, and no when-not guidance. The 'Metered: one Engine API call' note hints at cost trade-offs but does not route the agent between tools.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.