Tools

Each tool is one of the API's calls. Its arguments follow the same schema as the call's request body (or, for a GET, its query), taken from the OpenAPI document, so what works in a request works in a tool call. Its outputSchema is the call's answers in the same document: the report it gives, or the Errors body of a refusal.

The tools

Tool	Does	Arguments	Counts as
validate_linear	Checks a linear cut list without solving	LinearRequest	Free
solve_linear	Plans cutting parts from lengths of stock	LinearRequest	Solve
validate_sheet	Checks a sheet cut list without solving	SheetRequest	Free
solve_sheet	Plans cutting rectangles from sheets	SheetRequest	Solve
start_nest	Queues a true-shape nest	NestRequest	Job start
start_load	Queues a load plan	LoadRequest	Job start
job_status	Tells where a nest or load stands	{ "id": "…" }	Free
plan_report	Reads a finished plan: figures, layouts, export links; for a load, each space's loading steps and centre of gravity, and what didn't fit with why and the nearest fix	{ "id": "…" }	Free
usage	Reads the month's search time and the next lane, and on Free the loads left	none	Free
list_parts	Lists the workspace's saved nest parts, with the ids a nest's library takes	{ "unit": "mm" }, optional	Free
list_spaces	Lists the workspace's saved cartons, pallets and vehicles, as rows a load takes	{ "unit": "mm" }, optional	Free

Every length in a request is a string in the unit the request names, as on the web form. list_parts and list_spaces write sizes in the unit they are given, or the unit the key's owner picked on the web when it is left out; list_parts needs the Bench plan; list_spaces works on every plan.

The schemas are in the API reference; the guides for linear cutting, sheet cutting, nests, loads, jobs and plans and usage explain the fields.

How each tool behaves

Each tool carries MCP annotations, hints a client can use to decide what to ask the person before calling it:

Hint	Tools
readOnlyHint: true	validate_linear, validate_sheet, job_status, plan_report, usage, list_parts, list_spaces
idempotentHint: true	Every tool but start_nest and start_load, which queue a new job on every call
destructiveHint: false	Every tool: nothing deletes
openWorldHint: false	Every tool: each acts only in the key's workspace

The solves are not read-only, since each counts as a search, but the same cut list gives the same plan. To retry a start_nest or start_load safely, send an Idempotency-Key header: a retry with the same key, tool and arguments gets the first job back instead of queuing another. Idempotency and retries has the details.

What a tool answers

A tool's result carries the answer three ways, so any client can use it:

• content: two text parts, a one-line summary and the answer as JSON text.
• structuredContent: the answer as JSON, the same body the API call gives.
• isError: true when the call was refused, with the problems in the body. Errors has the shape.

A refusal is still a successful JSON-RPC answer: the HTTP status is 200, and isError says what happened. That includes a tool call past the workspace's per-minute budget. A request the server cannot read at all (no key, an unknown tool, a body that is not JSON) is a JSON-RPC error instead.

JSON-RPC errors

An error answer carries error.code and error.message, and the HTTP status that goes with it:

Code	HTTP status	When
-32700	400	The body is not JSON, or not text.
-32600	400	The body is not one JSON-RPC 2.0 message (a batch included), the MCP-Protocol-Version is one the server does not speak, or the Idempotency-Key is not 1 to 255 characters.
-32600	401	No live API key; the message says where to make one.
-32600	403	A browser request from an origin other than the MCP server's or the portal's.
-32600	404	A path other than /.
-32600	409	A tool call with this Idempotency-Key is still running.
-32600	413	The body is over 4 MB.
-32600	422	This Idempotency-Key was used for a different call.
-32601	200	No such method.
-32602	200	A tool call names no tool, or a tool there isn't; the message lists the tools there are.
-32603	500	Something went wrong on our side. Retry with the same Idempotency-Key.
-32000	429	Over a per-minute budget: the per-address budget, or the free-call budget for initialize and tools/list.

An over-budget initialize or tools/list is HTTP 429 with a -32000 error, while a tool call past the workspace's budget is HTTP 200 with isError: true and the API's 429 problem in its result. A ping is answered with an empty result, and a notification (a message without an id, or a notifications/ method) with 202 and no body; neither counts against the free-call budget or goes in the request log, though both count against the per-address budget. Anything but a POST gets 405 with no body.

Exports

A finished plan's exports are files, so they are not tools. plan_report gives their links; fetch them from the API with the same key, as Exports shows.