Design and change floor plans to scale in 2D and 3D: walls, rooms, roofs, furniture and gardens.
Scored across 12 tools
Most tools map to clearly distinct lifecycle actions (create/list/rename/delete/open/edit/undo/redo/search), so misselection is unlikely. The only real overlap is between describe_plan and query_project (and query_project vs edit_project, both run scripts), but the descriptions explicitly separate computed facts from ad-hoc read-only queries and mutation.
Eleven of twelve names follow a clean snake_case verb_noun pattern (create_project, list_projects, edit_project, undo_change, etc.). The lone exception is account_profile, which is noun-only and breaks the verb convention, but overall the set is predictable.
Twelve tools is well within the sweet spot for this domain. The server wisely consolidates the enormous design surface into script-based edit_project and query_project rather than exploding into dozens of granular geometry tools, while keeping account/UI actions as small discrete tools.
Project lifecycle is well covered: create, list, rename, delete, open editor, describe, query, edit, undo/redo, plus catalog search and account identity. Minor gaps exist (no project duplication/clone, no export or import tool despite exports being referenced, no sharing/versioning beyond 50-step undo), but the scripting API covers the design domain comprehensively.
The stable identifier of the linked Simple House Planner account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the notion of a "linked" account, without explaining what happens when no account is linked (error vs. null), whether the value is cached or live, or any auth requirement. For a zero-parameter lookup, that behavioral context is essentially absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short sentence with no wasted words, but that brevity comes from under-specification rather than economy. The sentence is not front-loaded with an action, so the reader learns a property of the account rather than the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure needn't be explained. However, for a zero-arg read tool the description should still establish the operation and any failure mode (e.g., unlinked account), and it does neither. The result is a definition too thin to let an agent confidently decide to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter meaning for the description to supply; the baseline of 4 applies. Nothing in the text misleads about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The text is a noun phrase describing a data attribute ("The stable identifier of the linked Simple House Planner account") rather than stating what the tool does. It never says whether account_profile retrieves the account, returns its ID, or checks linkage, so an agent cannot form a verb+resource understanding. It does at least signal the account domain, distinguishing it from the project-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of any alternative among the eleven siblings. Nothing indicates whether this should be called before project operations, on startup, or only when an account reference is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks to design, draw or plan a house, apartment, office, room or floor plan, and no plan of theirs fits. Starts a new empty plan to scale in their account and returns its ID. Build it with edit_project and show it with open_editor; do not describe a design in words or generate a picture of it instead.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | The plan's name, such as Lake house. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds meaningful context beyond that: the result is empty, it is created to scale, it lands in the user's account, and the call returns an ID that later calls need. It doesn't state that repeated calls create separate plans, though the workflow sentence partly compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The trigger is front-loaded, the effect and return value come next, and the closing sentence redirects to the correct tools and rules out the wrong behavior. Every clause carries weight, and the object list is short enough to justify itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter creation tool with no output schema, this covers the trigger, the effect, the return value, and the follow-up path (edit_project, open_editor). An agent has everything it needs to call this correctly and route the next step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the schema example ("Lake house") already conveys the naming intent. The description adds no further guidance on naming the plan, so it doesn't beat the baseline established by a fully documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ("Starts a new empty plan") and states the return value ("returns its ID"). It also scopes the object types it covers (house, apartment, office, room, floor plan), which separates it from siblings like edit_project and open_editor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ("when someone asks to design, draw or plan..."), an explicit precondition ("no plan of theirs fits"), named follow-on tools (edit_project, open_editor), and explicit exclusions ("do not describe a design in words or generate a picture"). Nothing about when to reach for this tool is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently deletes one plan from the person's account. It cannot be restored. Call this only for a plan that the person named in words. When they name none, as in "delete my plans", do not call this: call list_projects, show the titles and ask which ones to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds the crucial irreversible consequence ('It cannot be restored'), which the annotations do not convey; it stops short of saying whether anything attached to the plan is also removed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, ordered as action, consequence, guardrail. Every sentence carries distinct information and the destructive warning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with full annotation coverage and no output schema, the description covers action, irreversibility, and the ambiguous-request fallback. The only minor gap is whether deleting a plan also discards its contents such as furniture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains project_id's origin and that it must not be shown to the person. The description's contribution is limited to the provenance rule that the plan must have been named in words, which is usage guidance rather than added parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Permanently deletes one plan') and scopes it to 'one plan from the person's account', which separates it from rename_project and edit_project, which modify rather than remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition (call only for a plan the person named in words), an explicit exclusion ('delete my plans' with no named plan), and the alternative to use instead (list_projects, then show titles and ask). The agent has no inference left to do.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Facts that the planner computes for the site and for a floor or every floor: the site's location, time zone and north, rooms with areas and sizes, what each door connects, window directions, routes from the entrance, and warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| floor | No | ||
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context by framing results as facts the planner *computes* (derived rather than stored) and by advertising a warnings section, but it says nothing about result size, computation cost, or what happens when a referenced floor has no data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with no filler; every listed item corresponds to real returned data. It is slightly back-loaded, since the vague framing "Facts that the planner computes" precedes the informative enumeration, but nothing is expendable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return contents, and it does so well by enumerating rooms, doors, windows, routes, and warnings. Gaps are minor: the shape of the response, whether warnings are always present, and how large a full-plan response can be are left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: project_id is documented (including the notable "never show it to the person" constraint) while `floor` has no schema description. The phrase "for a floor or every floor" partially compensates by implying the omit-vs-specify semantics, but the description never states the indexing base (the schema's minimum of 0 suggests zero-based) or what an out-of-range floor yields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun-phrase inventory rather than a verb, but it names the concrete resource precisely: site location, time zone, north, room areas, door connectivity, window directions, entrance routes, and warnings. That enumeration makes it distinguishable from siblings like query_project or list_projects, even though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"for the site and for a floor or every floor" implicitly tells the agent that omitting `floor` yields full-plan facts while supplying it narrows to one floor. However, there is no explicit statement of when to prefer this over query_project or list_projects, and no exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes a plan with a short script of plan operations, which the person's open editors show at once. Returns the IDs that changed, the warnings and a description of every floor. A change is never final: undo_change takes it back and restores what it removed, for the last 50 changes.
JavaScript that changes the plan through the global object plan, run as one transaction: when any call fails, nothing changes and the error names the line. return a value to see it in the result. There is no network, clock or randomness.
plan.brief() → the answers the person gave when starting the project, or null: {floors, bedrooms, bathrooms, area (living area in m²), kitchen (open or separate), office, roof, plot ([width along the street, depth] in mm), street (the compass side the street runs along), site (flat, slope or water), slope (percent), downhill (the compass side the ground falls toward, where water lies), patio, pool, beds, fence, parking (garage or carport, when they want one), basement, roofTerrace, notes (wishes in their own words)} plan.floors() → [{floor, name, height}] plan.elements(floor) → elements in the file shape plan.get(id) → the element in the file shape, with its floor plan.describe(floor) → rooms with areas and sizes, what each door connects, window directions, routes and warnings plan.warnings() → warnings on every floor plan.check(rules) → [{floor, ids, message}]: the plan checked against a rule set beyond the layout warnings, each warning naming its part of the rules: "din18040-2" (DIN 18040-2, barrier-free dwellings without the wheelchair requirements: door widths and heights without thresholds, bathroom doors that open outward, hallways 1200 wide, 1200 × 1200 free in every room and in front of toilets, basins and showers, 1200 in front of kitchen fittings and 900 in front of cupboards, 1200 along one long side of a bed and 900 along the other, level showers 1200 × 1200, a window sill of 600 or lower in living rooms and bedrooms, straight stairs with handrails on both sides) or "irc2021" (IRC 2021 in part: room areas, widths and ceiling heights, glazing, emergency escape openings from sleeping rooms, the egress door, hallway widths, stair widths, risers, treads, headroom and handrails, spiral stairs, and guards). Rooms are known by their names, such as bedroom, bathroom, kitchen and hall plan.search(words) → catalog items {item, name, category, width, length, height} plan.addFloor(name, height?) → the new top floor's index plan.setFloor(floor, {name?, height?}) plan.wall(floor, from, to, {thickness?, height?, material?, curve?}) → wall id; curve bends the wall into an arc whose middle lies that far from the straight line, to the left of from → to (negative bends it right), at most the wall's length. material Glass makes a wall of glass in a slim metal frame with a mullion at least every 3000, for meeting rooms and offices or a glazed facade plan.walls(floor, points, {closed?, thickness?, height?, material?, curve?}) → wall ids, joined at every corner; curve bends every wall alike plan.circle(floor, center, radius, {thickness?, height?, material?}) → wall ids: four curved walls that close a round room or tower, radius to their centerline; doors and windows fit on them like on straight walls plan.room(floor, name, min, max, {thickness?, floorFinish?, floorColor?, wallFinish?, wallColor?, storeys?}) → {room, walls}: a room of its own with four walls around the inside corners min and max plan.marker(floor, name, at, {floorFinish?, floorColor?, wallFinish?, wallColor?, storeys?}) → room id: names the walled area around at. storeys (1) makes a room two or more storeys high, such as a great room or an entrance hall open to the floor above: the floors above leave its area open as a void, so give the floor above walls or a railing along the void's edge plan.door(wall, offset, {kind?, width?, height?, elevation?, hingeAtEnd?, opensOutward?, head?, open?}) → door id; offset is from the wall's from point to the door's center. kind is standard, glass (a glass leaf in a metal frame, as for a meeting room in a glass partition, where a standard door also has a glass leaf), sliding, pocket, barn, bifold, garage (a sectional garage door, 2500 wide) or open. open is how far a standard or glass door's leaf stands open, up to 180 degrees, or a bifold door's panels fold, up to 90, and how far a sliding, pocket or barn door slides open or a garage door rolls up, in percent of its travel up to 100, as the 3D view and renders show it. head is flat (the default), round, segment or pointed for an arched top, whose crown is at the height; on a curved wall the door follows the curve. plan.set(id, {frameColor}) colors its frame, lining and casings in a #rrggbb color, as for black steel doors plan.window(wall, offset, {kind?, width?, height?, elevation?, hingeAtEnd?, opensOutward?, head?, open?}) → window id; elevation is the sill height, head an arched top as for a door, and open how far its sashes stand open, up to 90 degrees. plan.set(id, {frameColor}) colors its frame and sashes in a #rrggbb color, as for black steel windows plan.furniture(floor, item, at, rotation?) → id; rotation in degrees counterclockwise, and at 0 the item's back, or a bed's head, faces +y. An item that hangs under the ceiling, such as a ceiling lamp or an AC cassette, starts there, and one that hangs on a wall at its usual height; plan.set(id, {elevation}) moves it up or down. A car shows a detailed 3D model in its paint, and plan.set(id, {paint}) repaints it in a #rrggbb color. plan.set(id, {finishes}) dresses the stuffs of a catalog item's model: wood, fabric (upholstery), linen (bedding and cushions), ceramic, metal and rug, each as {finish?, color?}: a finish, which color tints when it is tinted, or a plain #rrggbb color, such as {wood: {finish: 'black-marble'}, fabric: {finish: 'leather', color: '#5b3a29'}}. Lamps light the 3D view at sunset and at night: downlights, spotlights, track lights, LED panels, cove and under-cabinet strips, chandeliers, pendants and sconces (search lighting), and wall lanterns, up and down wall lights, step lights, bollards, path lights, garden spotlights, in-ground uplights, pool lights, string lights and lantern posts (search outdoor lighting). A wall light's back goes against the wall, a garden spotlight shines up and a little toward its back, and a pool light goes inside a pool, where it stands on the bottom and makes the water glow plan.against(wall, offset, item, room) → id: the item's back, or a bed's head, against the wall's face inside the room plan.stair(floor, from, to, width?) or (floor, points, {width?, style?, railing?, elevation?, height?, treads?, stringers?, beam?, balustrade?}) → id, or the ids of its flights: a stair that climbs from from to to, or flights that climb through the points in order and meet at a landing as deep as the stair is wide at each point between them, in line for a long stair broken by a landing or at a turn for an L or U stair. plan.set(id, {curve}) bends a flight into an arc whose middle lies that far to the left of from → to (negative bends it right), as a wall's curve, with winder treads that narrow toward the inside; a curved flight runs on into the flights joined to its ends without a landing where they meet in line, so a quarter-circle flight between two straight ones turns a corner on winders, and one curved flight makes a sweeping curved stair. style is solid, stringers, floating or spine, and railing left, right or both; the railings run on round the landings. A stair climbs from the floor (elevation 0) to the floor above (height, the floor's height + 200) unless elevation and height say otherwise: a half-floor stair to a terrace or deck ends at its top, and one down to a jetty starts below the floor at a negative elevation. Where a stair arrives at a platform's edge, the platform's railing leaves a gap for it. Its parts each take a material, Wood (oak), Steel, Glass, Concrete or Stone (travertine), and sizes in millimeters: treads {material, thickness} (50 on stringers, 80 floating, 60 on a beam; a solid stair's treads are its body, without a thickness), stringers {material, width, depth} (50 × 280, on stringers only), beam {material, width, depth} (160 × 220, on a center beam only) and balustrade {material, height} (the handrail's top above the treads' noses, 900; with a railing only): a balustrade of Steel or Wood is a handrail on balusters, of Glass a handrail on glass panes, and of Concrete or Stone a solid wall; all are Wood but the Steel balustrade unless given, such as {treads: {material: Glass, thickness: 40}, stringers: {material: Steel, width: 15, depth: 300}, balustrade: {material: Glass}}. plan.set gives a flight these fields too plan.spiral(floor, at, diameter?) → id: a spiral stair centered at at that climbs to the floor above in one counterclockwise turn from its -y side; plan.set changes its turn in degrees, clockwise, steps, rotation, railing (outer), elevation to start above the floor, its style, column (wedge treads on the center column), solid (solid steps stacked round the column) or stringers (treads between two stringers that wind up along its inner and outer edges), and its parts as plan.stair's: treads {material, thickness} (60; none when solid), column {material, diameter} (Steel, 120), where the treads start, stringers {material, width, depth} (Steel, 20 × 300) and balustrade {material, height} plan.builtIn(floor, style, from, to, {depth?, height?, elevation?}) → id: a built-in centered on the line from from to to; style is counter, upper (wall cabinets), tall (tall cabinets such as a pantry), closet (a built-in wardrobe), shelves, bench or desk, and each has its own depth, height and elevation unless given. plan.set(id, {finish, color, worktop}) dresses it: finish (any finish, such as oak or rustic-planks) or color (a #rrggbb paint, such as a dark kitchen island) for its fronts and sides, and worktop for the top of a counter or desk or a bench's seat, such as granite, marble, black-marble, terrazzo or concrete plan.alongWall(wall, start, end, style, room, {depth?, height?, elevation?}) → id: a built-in with its back against the wall's face inside the room, from offset start to offset end along the wall; keep the offsets clear of the walls at its ends plan.roof(floor, {shape?, pitch?, overhang?, eaveHeight?, finish?, color?, gutters?, rafters?, parapet?, followWalls?, trimColor?, gableFinish?, gableColor?, glazedGables?, at?, from?, to?, width?, min?, max?}) → id: a roof fitted to the walls around at (the middle of the floor's walls), or placed by its ridge from from to to with width its span across the ridge, overhang left out, or over the rectangle from min to max with its ridge along the longer side, as for a wing, a porch or a dormer; eaveHeight is the height of its eaves above the floor (the floor's height). Roofs on one floor meet in valleys: a dormer, a roof over the dormer's own walls with its eaves higher than the main roof, opens the main roof behind its glass, and a wing's roof joins the main roof. shape is Gable, Hip, Shed or Flat; gutters (true) hang along the eaves with downpipes that end on the roof, platform, floor or ground below them, rafters (false) shows a pitched roof's rafter tails under its eaves, parapet is the wall height around a flat roof's edge, followWalls (true) makes a flat roof trace the outer faces of the walls under it, curves and angles included, and stay open over courtyards (walled areas with no room marker), instead of its rectangle, and trimColor colors the fascia, gutters, coping and the frames of glazed gables. A gable or shed roof closes its gable ends: a wall under a gable end that is taller than the eaves (plan.set(wall, {height})) rises into the gable and closes it with its own finish, glass, doors and windows, so a window can sit high in the gable; gableFinish is a wall finish for the rest of the gables (the finish of most of the floor's outer walls), gableColor tints a tinted one, and glazedGables (false) makes them framed glass, as for a chalet plan.surface(floor, kind, min, max, {level?, depth?, infinity?, round?, water?, flow?, grassLength?, grassDensity?, plants?, edging?}) or (floor, kind, outline, {curves?, level?, depth?, water?, flow?, grassLength?, grassDensity?, plants?, edging?}) → id: an outdoor surface (lawn, path, driveway, road, sidewalk, patio, deck, gravel, bed, planter, terrace, sunken, court, pool or water) between the corners min and max, round ({round: true}, the ellipse that fills that rectangle, as for a round bed or pond), or with an outline of any shape through its corners in order, as [[x, y], …], whose edges curves bends: for each corner, how far the edge from it to the next corner bulges out at its middle in millimeters (0 straight, negative bulges in, at most the edge's length), for curved paths, kidney pools, and lakes and rivers with winding shores; plan.set(id, {outline, curves}) changes them. A road, a court, sunken seating and a pool with a vanishing edge keep their rectangle. A court is a sports court painted for basketball, a full court when 26000 or longer and a half court from its first end when shorter; put a basketball_hoop at each baseline. A road is asphalt with white edge lines and, when 4500 or wider, a dashed middle line along its longer side; plan.road lays a road along a path, and roads join where they meet (see road); a sidewalk is a 150 high concrete walk whose sides are its curbs. A lawn takes {grassLength (110 mm, 10 to 2000, such as 40 for a mown lawn or 400 for a meadow), grassDensity (10 tufts on a square meter, 1 to 100)}; a bed or a planter takes {plants: the plants that grow mixed in it, from flowers, shrub, agave, bamboo and cactus ([flowers]; [] for bare soil), edging: none, stone (the bed's), brick, steel (corten, the planter's) or timber}; grass and plants sway in the breeze in 3D. A planter is a raised bed, 450 high; a terrace is a raised paved area, 450 high; sunken is sunken seating: a pit depth (700) deep with a bench round its walls and steps down at the min end of its longer side. Water is {water: lake (the default), sea or river}, whose surface lies level millimeters above the floor (-1500) and whose ground sinks to depth (2500) below it, with shores that slope up from it; in the 3D view a lake ripples, the sea rolls in waves, and a river flows along its banks in the direction flow, [dx, dy] on the plan, which runs along the longer side of a river between two corners and toward max without one, and toward +y for an outline without one; and a pool takes a depth. A patio, deck, driveway, terrace, sunken seating, court or pool sits level at level millimeters above the floor (0), and the ground slopes up or down to it at 1 in 2; on an upper floor, such a surface and any other that the ground rises to, as at the street level of a house that steps down a hill, becomes part of the terrain at its floor's level the same way; {infinity: true} makes the pool's short end nearest max a vanishing edge, with its water running over a low wall there, for a pool at the edge of a terrace with a view plan.surfaceAt(floor, kind, from, to, width, {level?, depth?, infinity?, curve?}) → id: a surface of any kind that runs from from, the middle of one edge, to to, the middle of the opposite edge, and is width across, at any angle; a pool's vanishing edge is its edge at to, so plan.surfaceAt(0, "pool", [5000, 4000], [5000, 0], 10000, {infinity: true}) makes a pool 10000 long and 4000 wide whose long side at y 0 is the vanishing edge; curve bends a road into an arc whose middle lies that far to the left of from → to (negative bends it right), at most the distance between them plan.road(floor, points, {width?, curves?}) → ids: a road through the points in order, a stretch width (7000) wide from each point to the next whose middle bulges curves[i] to the left of points[i] → points[i + 1] (negative to the right, 0 or left out for a straight stretch), the stretches meeting end to end with the outside of each bend rounded. Roads join wherever an end of one lies on another, at a T, a corner or a shared end, and where they cross; there the curbs round the corners with a 6000 radius, the edge lines follow the curbs round into the other road, and the dashed middle lines stop short of the junction. plan.set(id, {curve}) bends one stretch plan.fence(floor, from, to, style?) → id: a fence of style rails, boards (the default), pickets, panels or hedge plan.run(floor, kind, points, {width?, height?, elevation?, drop?}) → ids: a duct or cable tray along points [[x, y], …], one run between each two; kind is round (a round duct 250 across, width its diameter), rect (a rectangular duct 500 wide and 300 high) or tray (a cable tray 300 wide with sides 80 high). elevation is its underside above the floor (200 under the ceiling). Runs of a kind join where they end: two on an elbow, three or more, or one that ends on another's middle, on a tee, a larger run narrowing to a smaller one on a reducer, and runs where one reaches above or below the other through an upright piece. drop turns the last run down that far below its underside at its end, where a duct ends in a grille; plan.set(id, {drop}) gives any run one at its to end plan.platform(floor, kind, min, max, {elevation?, railing?, supports?, finish?}) or (floor, kind, outline, {…}) → id: a platform between the corners min and max, or with an outline of any shape through its corners in order, as [[x, y], …], such as an L-shaped deck or one that wraps round a corner of the house, which plan.set(id, {outline}) changes (a rectangle takes {outline, at: null, width: null, length: null}); kind is balcony, deck (a deck on posts), walkway or pier, and each has its own elevation (its top above the floor, negative for a jetty down at the water below the floor), railing (none, bars or frameless glass, along every edge that no wall, other platform, arriving stair or, at the floor's level, pool runs along), supports (none, posts, piles, or caissons: concrete piers 1000 across that hold a platform out from a steep slope, down to the ground) and ground finish unless given plan.balcony(wall, start, end, depth?, {elevation?, railing?, supports?, finish?}) → id: a balcony against the wall's outside face, from offset start to offset end along it and depth (1500) deep; put a door in the wall to reach it plan.plot(points) → plot line ids around the plot on floor 0 plan.spot(at, level) → id: a spot height on floor 0 where the surveyed ground lies level millimeters above the floor; three or more shape the terrain, which keeps the site's slope far from them and stays level under patios, decks, driveways, terraces, sunken seating and pools, and under the house unless the grading is natural; a plan.wall that encloses nothing retains the ground behind it, and an upper floor that reaches past the floors under it into ground as high as its own level is dug into the slope, so that a house steps down a hill floor by floor plan.breakline(points) → ids: a breakline of the existing ground on floor 0 through points [x, y, level] in order, such as the top or the toe of a bank or the bottom of a ditch; the terrain between the spot heights and the breaklines follows each breakline as a straight edge from level to level plan.slope(percent, downhill, {at?, level?, size?}) → spot ids: replaces the spot heights with a site that falls percent in a hundred toward the plan direction downhill, such as [0, -1], and lies at level (0) at at (the middle of the bottom floor's walls), over a square size (60000) wide plan.site({grading?, ground?, winter?, banks?, surroundings?, contourInterval?}) → {grading, ground, winter, banks, surroundings, contourInterval}: grading level (the default) levels the ground around the house to the bottom floor; natural keeps the ground's shape, so that a house on a hillside is set into the slope, its walls holding back the ground uphill and reaching down to it downhill. ground is the finish that covers the site: grass (the default), sand, desert-sand, dry-earth, rock, forest-floor, moss, fallen-leaves, soil, gravel or another ground finish, or none for no ground at all, as for an apartment. winter is what winter brings to everything outdoors when the date of the 3D view's sun falls in winter: frost (the default), snow on every face that looks up, or mild for neither. On sand, desert-sand and dry-earth lawns are dry all year and no snow or frost falls; rock follows winter, so a mountain site can be snowy. Ground steeper than about 32° shows scree, and steeper than about 45° rock; banks, scree or rock, covers the slopes of cut and fill, and surroundings, a ground finish, the ground beyond a closed plot, each null for the ground cover. contourInterval is the height in millimeters between the contour lines of the plan, or null for one that suits the range of heights plan.info({title?, client?, address?, author?, north?, latitude?, longitude?, mapOrigin?, mapSystem?}) → {title, client, address, author, mapOrigin, mapSystem, latitude, longitude, zone, north}: the project information for title blocks, and where the site is. latitude and longitude are the site's place in degrees, north and east positive, set together (null removes them); they place the 3D view's sun and its shadows, on the clock of the site's time zone (zone), which follows from them. north is the degrees counterclockwise from the plan's +y axis to true north (0). mapOrigin is where the plan lies on the map: [east, north, height] in millimeters, the map coordinates of the plan's origin at the bottom floor's level, and mapSystem names the map's coordinate system, such as EPSG:25832; each null removes it. Survey imports place their points by them, and DXF, DWG and IFC exports place the plan on the map plan.finishes(use?) → [{key, name, uses, tint}]: the finish library, or the finishes for one use: wall, floor, roof, ground or object (furniture, built-ins, railings and the parts of shapes and items). A tinted finish takes a color plan.defineItem(key, {name, category?, keywords?, mount?, elevation?, lumens?, beam?, up?, kelvin?, parts} or {name, category?, keywords?, mount?, elevation?, lumens?, beam?, up?, kelvin?, children}) → key: adds or replaces a furnishing item of the project's own, which plan.furniture, plan.against and plan.search then use like a catalog item, and which people find in the Furnish tab. Make an item of anything placed more than once, such as a custom chair, a planter box or a light fitting. parts are as plan.shape's; the item is the box around them, and at rotation 0 its back faces +y. mount is floor (the default), wall, ceiling or roof: a ceiling item is placed under the ceiling, a wall item snaps to walls when people move it, and a roof item, such as a rooftop unit, stands on the highest roof of its floor under it, or on the floor where no roof is; elevation is the height of a floor or wall item's underside when placed (0), and of a roof item's above the roof; lumens makes the item a lamp whose parts with look glow give off its light, all round from their middle unless beam (degrees) makes each glowing part a spotlight along its own -z axis, which points down until the part turns (rotation [180, 0, 0] points it up), and beam 180 a panel, as for an LED strip; up (degrees, with a beam under 180) makes each glowing part also shine up in that cone along its +z axis, as the shade of a table lamp or a sconce open at both ends does; kelvin is the lamp's usual color temperature (2700). children combine items: [{furnishing, x, y, angle?, width?, length?}]. key is lowercase letters, digits, - and _. Replacing an item changes every furnishing that uses it plan.items() → the project's own items with their keys and sizes plan.removeItem(key) → removes an item that no furnishing uses plan.shape(floor, at, parts, {name?, rotation?, elevation?, draft?}) → id: any form, made of parts measured from at in the shape's own frame (x across, y along, z up from elevation), turned rotation degrees counterclockwise. It stands on the ground under its middle on any slope, so elevation counts from that ground and not from the floor: leave it out for a shed or a sculpture on a hillside, and make it negative only to sink the shape into the ground. With a draft it floats, as a boat, a buoy or a raft does: over a lake, the sea or a river its base lies draft millimeters under the water's surface, and on land it stands on the ground; plan.set(id, {draft}) makes a furnishing float the same way. Each part is {name?, solid, at? [x, y, z], rotation? [x, y, z] degrees, finish?, color?, look?} with the solid's fields: box {size: [x, y, z]} and pyramid {size: [x, y], top?: [x, y] (0 for a point), height} stand on at; cylinder {radius, top? (its top radius, 0 for a cone), height, segments?}; sphere {radius} around at; prism {outline, holes?, height} lifts a plan outline; lathe {profile: [[radius, z], …], segments?} turns a profile round the vertical axis; loft {sections: [{outline, z}, …]} joins outlines of equal point counts; mesh {vertices, faces} is any solid of triangles or polygons counterclockwise from outside. A radius is a number or [x, y] (sphere [x, y, z]). finish is any finish of the library, color a #rrggbb tint or plain color, look matte, metal, glass, water or glow. Write a loop to build towers, roofs, stairs or ornaments from many parts; plan.get returns the parts as written, with at, rotation and the size of the shape's box when it was stretched plan.finishFace(wall, side, finish, color?) → wall: finishes one whole face of a wall, as for an accent wall, in place of the finish of the room it looks into or of the wall's outside; side is left or right, looking from the wall's from to its to, or a room id for the face that looks into that room; finish is a wall finish, and color a #rrggbb tint for a tinted finish such as paint. null for the finish gives the face back its room's or outside finish. plan.get(wall).faces lists them. Coverings lie over a face's finish plan.cover(wall, side, {finish, color?, from?, to?, bottom?, top?}) → wall: covers part of one face of a wall with a finish, such as tiles up to 1200 in a bathroom, a splashback over a kitchen counter or a stone plinth outside. side is left or right, looking from the wall's from to its to, or a room id for the face that looks into that room. from and to are millimeters along the wall (its whole length, or the stretch that borders the room), bottom and top heights above the floor (the whole height); doors and windows stay open. plan.get(wall).coverings lists them, and plan.set(wall, {coverings}) changes them plan.section(floor, from, to, name?) → id: a section line, named A, B and so on unless name is given; its section cuts the whole house along the line, through walls, slabs, roofs, stairs and the ground, looks to the left of from → to and spans the line's length. The Elevations and sections dialog shows it, and PDF and DXF exports put the sections on a sheet of their own plan.label(floor, text, at) → id plan.set(id, fields) → changes fields in the file shape; null removes an optional field plan.remove(id) → deletes the element and the openings in it
Points are [x, y] in millimeters. Floors count from 0 at the bottom. Furniture items are keys from plan.search or search_furniture. Lamps (search "lighting" or "outdoor lighting") light the 3D view: plan.against puts a wall lamp on a wall, ceiling lamps hang from the ceiling, and plan.set(id, {lumens, kelvin, on}) sets a lamp's output, its color temperature and whether it is on.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | A few words for the plan's history, such as Add a garage. | |
| script | Yes | ||
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare that this is a non-read-only, non-open-world operation, but the description adds substantial behavior beyond them: changes appear immediately in open editors, the script runs as a transaction where a failure leaves everything unchanged and names the failing line, there is no network, clock or randomness, and undo_change restores removed work for the last 50 changes. It also discloses deletion behavior via plan.remove while explaining that it is undoable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is front-loaded with purpose, return values, undo behavior and transaction semantics before the API reference, which gives it useful structure. However, it is extremely long and reads like a full reference manual embedded in a tool description, with many low-level defaults and material details that make it heavy for an agent to scan during tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of an output schema, the description is unusually complete: it explains the return values, the atomic transaction behavior, the undo window, the immediate editor update, and the full scripting surface. There are no material omissions for an agent that needs to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 67% because the script parameter has no schema description, but the description fully compensates by documenting the JavaScript execution model, the global plan object, transaction semantics, and an extensive list of operations with their arguments and return shapes. The remaining two parameters are documented in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource ('Changes a plan') and the exact mechanism ('a short script of plan operations'), plus the immediate effect on the person's open editors. It also names undo_change as the revert path, distinguishing normal editing from undo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear that this tool is for changing a plan, and it mentions undo_change as the way to take a change back. However, it does not explicitly say when to choose this over read-oriented siblings such as describe_plan or query_project, nor does it state any exclusions or prerequisites for editing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone mentions one of their plans or asks what plans they have. Lists the plans in their account with titles, floors and last changes, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuine value beyond that by disclosing the returned fields (titles, floors, last changes) and the sort order (newest first). It does not mention any result cap or pagination, which is the only remaining behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The usage trigger is front-loaded ahead of the output description, which is the right ordering for an agent deciding whether to call.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no input parameters and no output schema, the description carries the return-value burden itself and does so for the main fields and ordering. A note on result size or whether all plans are always returned would close the last gap for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is no parameter meaning to convey and the baseline applies. The description correctly implies the call is unfiltered ('the plans in their account') rather than suggesting optional scoping arguments that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Lists the plans in their account') and names the fields returned plus the ordering, so the agent knows exactly what comes back. It does not explicitly differentiate from describe_plan, which also deals with a single plan, so a user 'mentioning one of their plans' could plausibly route either way.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete conversational trigger ('when someone mentions one of their plans or asks what plans they have'), which is clear context for invocation. It offers no exclusions or named alternatives, so the boundary with describe_plan and query_project is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows a plan in the Simple House Planner editor, where the person can change it by hand in 2D and 3D and sees your changes as you make them. Without a project ID it shows their plans to choose from.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered, and the description usefully clarifies that mutations come from the human in the UI ('change it by hand in 2D and 3D') plus that the view updates live. It omits key behavioral facts for a UI-opening tool: whether the call blocks or returns immediately, whether it requires an active user session, and what value comes back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the primary action plus the interactive-editing behavior are front-loaded before the optional-parameter fallback. Every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single fully documented optional parameter, annotations covering the safety profile, and no output schema, the description covers what to pass and what happens when nothing is passed. The remaining gap is interaction lifecycle — whether opening the editor suspends the agent or returns a handle — which matters given this is a UI-invoking tool rather than a data read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains where project_id comes from and that it must not be surfaced to the person, so the baseline is 3. The description earns above baseline by documenting the semantic effect of omitting project_id (a chooser of the person's plans), which is not expressed anywhere in the schema and is the only optional-parameter behavior an agent must reason about.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Shows a plan in the Simple House Planner editor') and adds distinguishing detail that this is an interactive surface where the person edits in 2D/3D, which separates it from a plain read like describe_plan. It stops short of explicitly naming the sibling tools it differs from, so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
One usage branch is given explicitly: 'Without a project ID it shows their plans to choose from,' which tells the agent the parameter is genuinely optional and what happens on omission. However, there is no guidance on when to prefer this over describe_plan, query_project, or list_projects, and no when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs a read-only script for questions that describe_plan does not answer, and returns what it returns. Scripts work as in edit_project, but only plan.floors, plan.elements, plan.get, plan.describe, plan.warnings, plan.check and plan.search are available; plan.check("din18040-2") or plan.check("irc2021") checks the plan against DIN 18040-2 for barrier-free dwellings or the 2021 IRC.
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes | ||
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint false and openWorldHint false, and the description is consistent with them, adding real value by enumerating the sandbox surface (plan.floors, plan.elements, plan.get, plan.describe, plan.warnings, plan.check, plan.search) and the accepted check() argument strings. It stops short of disclosing execution limits, timeouts, or what happens when a script errors, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the selection criterion before the detail, and the whitelist of available APIs earns its space because it exists nowhere else. The phrase 'returns what it returns' is vague filler and the check() clause is dense, but nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description covers the essentials an agent needs: read-only scope, the script dialect's origin, the exact callable surface, and the regulatory check strings. Given only two parameters with no nested objects, remaining unknowns (error handling, rate limits) are marginal rather than blocking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: project_id is documented in the schema, but 'script' has no schema description at all. The description compensates well by explaining what a script may reference and which plan.* calls are legal, effectively documenting the opaque parameter's contract; it still does not describe script return/evaluation semantics precisely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Runs a read-only script', 'Query plan') and positions it directly against two siblings: describe_plan for standard questions and edit_project for the script dialect. An agent can distinguish this from every other sibling without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit selection rule: use this for questions describe_plan does not answer, implying the converse (use describe_plan when it suffices) and pointing at edit_project for the mutation counterpart. That is when-to-use plus alternatives, which is the top of the scale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Makes again your own last change to a plan. The person's own edits stay as they are.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely non-obvious context: the scope is limited to the caller's own last change, and other people's edits are preserved. It stops short of covering failure behavior when the redo stack is empty, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the action front-loaded and the side-effect guarantee second. No wasted words, though 'Makes again' is less crisp than 'Reapplies' and slightly slows parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation with annotations and no output schema, the description covers the essential scope. It omits the paired undo_change relationship and the no-op/error case, which an agent would need to call this confidently in a redo workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, and schema description coverage is 100% – the schema already explains project_id and even the display rule. The description adds nothing further about the parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb-like action ('Makes again') on a specific resource ('your own last change to a plan'), which implicitly contrasts with the sibling undo_change. However, it never names undo_change or explains that this is the inverse operation, so the differentiation is left to inference and the phrasing is slightly awkward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The trigger condition is implied by 'Makes again your own last change' – an agent can infer this is used to reapply a reverted edit. But there is no explicit when-to-use, no mention of the undo_change alternative, and no guidance on what happens when there is no change to redo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes the name of a plan in the person's account.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=false, so the safety profile is covered. The description adds only the scope detail that the plan lives in "the person's account"; it says nothing about title collisions, whether the previous name is recoverable via undo_change, or what a successful response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no wasted clauses. It is efficient but borders on under-specification rather than tight writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with annotations covering safety and idempotency and no output schema, the description is minimally adequate. Gaps remain around the effect on the previous name, error conditions, and how this differs from edit_project.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: project_id is well documented in the schema but title carries no description anywhere. The description does not compensate by explaining that title is the new name to apply, its length/format constraints, or uniqueness rules — the single most important unknown for the caller is left unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ("Changes the name of a plan"), so an agent knows exactly what operation this is. It does not, however, distinguish itself from the sibling edit_project, which plausibly also modifies a plan's name, and it drifts between "plan" (description/title) and "project" (tool name/schema), leaving a minor terminology ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance at all: nothing says to prefer this over edit_project for renames, nor any precondition such as existing ownership of the plan. The agent must infer the routing decision entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds furniture in the catalog by words such as bed, sofa or table, and by size such as w:1200. Use the item keys with plan.furniture and plan.against.
| Name | Required | Description | Default |
|---|---|---|---|
| words | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral information: that the result set is a list of item keys intended to be fed into plan.furniture/plan.against — a return-shape disclosure that matters because there is no output schema. It stops short of stating result limits, empty-match behavior, or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. The query capability is front-loaded and the follow-on usage note is placed second, which matches the order an agent needs them.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only search with no output schema, the description covers purpose, query syntax, and what the returned item keys are for. Marginal omissions remain around result count, no-match behavior, and multi-term semantics, but nothing essential for a correct first call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — the single "words" parameter is an undescribed string — so the description carries the full burden, and it largely does: it names example keyword values and documents an inline size syntax (w:1200) that is invisible in the schema. It leaves open whether size and keywords are combined in one string and how multiple terms are joined, which is the remaining gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ("Finds furniture in the catalog") and immediately shows the two query modes with concrete examples — keywords like bed/sofa/table and a size token like w:1200. No sibling tool touches furniture, so the agent can route here unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use the item keys with plan.furniture and plan.against" gives useful downstream workflow context — it tells the agent what to do with the results. However, it never frames when this tool should be chosen over another approach (e.g., vs. pulling a whole catalog), and no when-not guidance is present. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Takes back your own last change to a plan. The person's own edits stay as they are.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project's ID from list_projects or create_project. Never show it to the person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations cover the safety profile (destructiveHint=false, non-idempotent), and the description adds genuinely new scope information: only the agent's own most recent change is reverted, and the person's edits are unaffected. It still omits what happens after the undo (returned state or error when no change exists), which is relevant for a non-idempotent mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action, then the scope caveat about the person's own edits. No filler and nothing that could be cut.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with annotations and no output schema, most requirements are met, but the description does not say what the caller gets back after undoing, whether the undo is limited to the latest change only across all plans in the project, or how a no-op case behaves. The 'plan' vs project_id wording adds ambiguity that a complete description would resolve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single, fully documented project_id, so the schema carries the parameter semantics. The description adds nothing about the parameter and slightly conflicts by referring to 'a plan' while the param is project_id, leaving the plan/project relationship to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('takes back') and resource ('your own last change to a plan'), which is clearly distinct from the mutation siblings like edit_project. It does not explicitly name the reverse counterpart redo_change, so the sibling boundary is only implicit; it also says 'plan' while the sole parameter is project_id, a small naming mismatch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: 'your own last change' hints that this reverts a single most recent agent edit. There is no explicit when-to-use, no mention of redo_change as the opposite action, and no guidance on what to do if there is nothing to undo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
account_profilecreate_projectdelete_projectdescribe_planedit_projectlist_projectsopen_editorquery_projectredo_changerename_projectsearch_furnitureundo_changeFloor plans in real mm: doors, windows, fixtures; validate, render, elevations, sections, storeys.
Describe a house or upload a DWG/vector-PDF plan and get a walkable, editable 3D model.
Floor plan to measured 3D model: rooms and areas, furnishing, roof, solar, site and share links.
Inspect real parcels, create and edit urban plans, compare alternatives, and share 2D/3D designs.
Add one secure layer between your agents and this server.
