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

Annotations only flag readOnlyHint=false and destructiveHint=true. The description goes well beyond: it discloses that accepted findings stop counting toward score/pendencies/dry runs while remaining visible, that an empty reason reverses the action, that prune drops orphaned acceptances, and that the step is undoable. This is rich behavioral context beyond structured 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?

The main action is front-loaded, but the sentence is dense with nested parentheses, semicolons, and parenthetical asides that make it harder to parse than necessary. The information earns its place, but the structure is cluttered.

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-optional-param mutation with an output schema, the description covers triggers, reversibility, orphan handling, and confirms the ok/accepted/removed reply. It stops short of directing the agent to re-read the review as part of a workflow, but is otherwise complete.

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%, so both parameters are already documented with near-identical text to the description. The description reinforces the [[key, reason]] shape and the orphaned semantics of prune but adds little that the schema doesn't already convey, so the 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?

The description states a specific verb and effect: marking findings (layout, ergonomics, electrical, plumbing) as looked at via the key the review provides. It is clearly distinguishable from adjacent edit_* tools, though it doesn't explicitly name a sibling it competes with.

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 explains the core usage path (accept=[[key, reason]] to mark looked-at, empty reason to reverse) and the conditional prune=true path for orphaned acceptances. What's missing is any explicit statement of when NOT to use it versus sibling tools like feedback or edit_history.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows it's a safe read. The description adds some behavioral detail like the structure of `stale` output, but it contradicts the annotation by calling it 'Plan annotations, read' which is fine, but the annotation says readOnlyHint true; description says 'edit_annotations switches modes' which is a different tool, not a contradiction. However, the behavioral transparency is low because it doesn't disclose important traits like whether it requires authentication, rate limits, or side effects. It does add context about what 'stale' means, which is good, but with annotations covering safety, the bar is lower, yet this description still misses key behavioral aspects.

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 description is a run-on sentence with multiple clauses and parentheticals, making it hard to parse. It is not front-loaded well; the key purpose is buried in jargon. It lacks clear structure and could be broken into bullet points or shorter sentences.

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 complexity (read tool with two optional parameters, output schema exists), the description covers some aspects but misses important context like prerequisites, side effects (none expected), and how it relates to other annotation tools. It provides details on `stale` and `q` but not enough to fully understand the tool's behavior in typical workflows.

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 description coverage is 100%, so the schema already documents both parameters (`q` and `stale`). The description adds some semantic meaning: for `stale`, it elaborates on the return format and what counts as stale; for `q`, it mentions case/accent insensitivity and regex. However, it doesn't go beyond the schema significantly, and with full coverage, baseline 3 is appropriate.

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 opens with 'Plan annotations, read,' which states the verb and resource, and elaborates on what it reads (dimensions, tags, notes). However, it doesn't explicitly differentiate from the sibling `edit_annotations` beyond a brief mention that `edit_annotations` switches modes – it doesn't state that this tool is read-only and the other is write, leaving some 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?

It provides clear context by mentioning when to use `stale=true` and when to use `q`, and even points to `edit_annotations` for edits. Yet it doesn't explicitly say when not to use this tool or compare it to other read tools like `show_plan` or `measure`.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so mutation is covered. The description adds genuinely useful behavioral detail beyond that: the whole operation is "one undo step", group "moves/hides together", and flip "rebuilds what is inside it", which tells the agent about side effects.

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?

Front-loaded with the core purpose, then a dense but waste-free clause per action. It is a long block, but every clause carries action-specific meaning; readability suffers slightly from being one unbroken paragraph.

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 10-action tool with 16 parameters, the description covers every action and notes the return ("Returns new ids"), and an output schema exists so return shape need not be explained. It is nearly complete, lacking only positioning relative to sibling tools.

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?

With 100% schema coverage the baseline is 3, but the description adds real value by mapping parameters to actions (array {ids,n,dx,dy,dz}, align {ids,axis,edge,value}, distribute {ids,axis,gap?}), which the flat schema does not make explicit. This disambiguates the 16 shared parameters per action.

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 the operation type ("Arrange elements in one undo step") and then enumerates all ten actions with concrete domains (rafters, columns, joinery, pool over deck). An agent can tell this apart from siblings like move/place/joinery because the description makes clear it is the multi-action transform/grouping toolbox.

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?

Supplies per-action usage context, e.g. align instead of "centers you work out yourself", flip vs mirror ("mirror only swaps left and right"), and distribute for "a run of joinery". It does not, however, state when to reach for this tool over sibling tools such as move or place.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description reinforces this by stating results are returned 'without drawing'. It goes further than annotations by disclosing the detection heuristics (thick dark/gray bands, colored areas ignored, door/window gaps joined) and the luminance-based threshold behavior.

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 dense paragraph that is front-loaded with the detection rules and ends with the return shape and cross-references. Nearly every clause carries information, though the long em-dash construction is somewhat run-on and could be split for faster scanning.

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?

Output schema exists, so describing return values is not strictly required, yet the description still names the row format and units, which helps interpretation. Detection rules, preconditions, and verification tooling are all covered; only edge-case behavior (e.g., no walls found, very large scans) is left unstated.

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 description coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema for the two subtlest params: max_gap ('pieces split by doors or windows up to max_gap join') and region ('limits the search'), which make their effect on output concrete.

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 (detect walls in a scanned plan) and pins down the exact source of the image ('under the drawing, put there by edit_background action=set'). It is clearly distinguishable from siblings like edit_walls and edit_background, which create or modify rather than detect.

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?

Explains the precondition (a scan must already be placed via edit_background action=set) and routes the agent to related siblings for adjacent tasks (edit_background action=trace to create, render_plan bg=0.5 to verify). No explicit 'do not use this when…' exclusion among siblings, so it stops short of a 5.

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

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

Annotations mark destructiveHint=true and readOnlyHint=false, and the description corroborates by disclosing 'Replaces the cabinets already there (keep ids stay)' — the exact destructive scope — plus the dry-run escape hatch. It further sketches the return shape ({modules, removed, notes}), which is real behavioral context, though some of it overlaps the output schema.

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 purpose is front-loaded, but the bulk is a single sprawling sentence with nested parentheticals and semicolons that is hard to parse rather than efficiently scannable. Information density is high and most clauses earn their place, but the structure underserves it.

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 high-complexity 8-parameter tool with a nested `p` object and an output schema, the description covers the destructive lifecycle, defaults, appliance/wardrobe placement, and the keep-vs-replace contract. Return values need not be re-explained since an output schema exists; remaining gaps are minor edge-case semantics.

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% (baseline 3), but the description genuinely adds meaning: the EN 1116 rationale for target=60/max=90/sink_w=80/cooktop_w=60, the 15–30 cm pull-out and sub-15 filler fallbacks, and the placement rules for p.sink/p.cooktop (cabinet under it plus countertop cutout). These are semantic rules the schema cannot express, though they only partially disambiguate the addProperties-true `p` bag.

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 states a specific verb + resource + scope: 'Fill a wall with cabinets sized for it,' and the body expands into exactly what it generates (modules, drawer unit, countertop, wardrobe rows, appliance cutouts). It also names the sibling it is not for the post-edit step ('Change one module afterwards with joinery id'), so an agent can distinguish it from joinery/place/arrange without opening schemas.

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 context for when to reach for it (fill a whole wall/row, including appliances and wardrobes) and explicitly routes follow-up edits to the joinery sibling, plus the dry-run mode ('dry plans only'). It stops short of stating when NOT to use it versus place/arrange/layout, so it is clear but not exclusion-complete.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful unit context (cm and degrees) that annotations don't carry, but the structural field list largely duplicates the existing output schema.

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 compact sentences, with the data-shape summary front-loaded and the alternative tool noted last. The field notation is dense but not wasteful.

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 and annotations cover the safety profile, so the description only needs to orient the agent, which it does. Units and the edit_cameras pointer round out everything needed to call this no-arg reader.

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 nothing to document and the baseline is 4. The description does not need to compensate for any parameter gaps.

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 the resource (stored points of view) and effectively the read behavior, reinforced by the title 'List points of view'. It explicitly contrasts with the mutation sibling edit_cameras, so an agent can distinguish it without opening the 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 routes the agent clearly: view stored cameras here, but 'Change them with edit_cameras' for modification. There is no explicit when-not clause, but the read-vs-edit split is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety profile is covered. The description adds useful behavioral context: the row schema, front/wall/free semantics, and that scope=project lists what the plan already uses. It stops short of return format (though an output schema exists) or pagination behavior.

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 description is one massive run-on sentence with dense domain jargon (front semantics, +y local axis, plan angles) that could be separated. It is not front-loaded—the actual search purpose is buried at the start but the rest rambles into row formatting. Structure is poor despite conveying information.

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 an output schema present, the description needn't explain return values, and it does provide meaningful domain context about the front field. However, it omits guidance on how to search effectively (e.g., combining q and cat) and does not clarify the relationship to the project scope alternative. Adequate but with clear gaps.

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 description coverage is 100%, so all four parameters are already documented. The description adds interpretation of row structure and the semantics of the 'front' field, which is not in the schema, but does not add per-parameter detail beyond what the schema provides. Baseline 3 is correct.

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's opening 'Find catalog items' does state the verb and resource, and the schema covers search parameters. However, the bulk of the text describes row format, front semantics, and the project scope mode rather than distinguishing this catalog search from siblings like 'library', 'place', or 'edit_library'. Compared to a 5 that names the specific sibling it is not, this is adequate but not distinguishing.

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 mentions scope=project behavior but never states when to use catalog search versus library/edit_library or place. No explicit when-to-use or when-not-to-use guidance relative to the many sibling search/placement tools. Usage context is implied by the 'scope=project' mention but not framed as guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the atomicity trait (all primitives created in one step), which is genuinely useful, but says nothing about permissions, partial-failure behavior, or reversibility.

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?

Front-loaded with 'Create' and packs all resource types into one dense sentence with no filler. It is long, but for a 10-parameter multi-primitive tool every clause carries information, so the length is defensible.

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 breadth, the description enumerates all creatable primitives, and since an output schema exists it need not explain return values. The only gap is the absence of guidance on when to prefer it over sibling creation/edit tools.

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 description coverage is 100%, so every parameter and nested field is already documented in the schema. The inline hints (hs = height per point, at=[x,y], ceiling_flat=false follows wall profiles) largely restate schema content, so the description adds only marginal semantic value. Baseline 3 is correct.

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 the specific verb (Create) and enumerates every resource it produces: walls, rooms, dims, labels, roofs, solids. An agent can distinguish it from siblings like edit_walls or place without opening any schema.

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

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

The closing phrase 'in one atomic step' implies this is a batch-creation tool, which is useful context, but the description never names alternatives or states when-not-to-use it versus edit_walls, place, or move. Usage is only implied.

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

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

With readOnlyHint and openWorldHint already declared, the description still adds substantial behavioral content the annotations do not: the 50 mm board threshold, the 'board is its finish and thickness, no edge banding' rule, skipping of non-board parts as [[id,name]], and row merging by size/hardware/sheets. These tell the agent how output is derived and transformed. It does not cover auth or pagination, so it falls short of 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?

It is front-loaded with the core purpose, but the body is a jargon-heavy run-on stitched together with colons and semicolons, and the trailing panel-standard trivia (NBR 15316 / NBR 14810) is marginal for tool selection. The content is mostly substantive, yet the structure makes it hard to parse quickly.

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 the description ideally need not restate the return shape, yet it spends most of its length on row layout. Behavioral coverage of the core transformation is decent, but the absence of any usage or routing guidance leaves a real gap for an agent choosing among dozens of siblings. Adequate, not complete.

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 description coverage is 100% for the single optional 'ids' parameter, which already documents the default ('every build and drawn group on this storey'). The description adds no additional meaning about how ids are supplied or whether they can mix build and drawn-group ids, so the 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?

The description names a specific resource and scope: a cut list covering joinery builds and hand-drawn groups, with detail on what qualifies as a board (<=50 mm thick) and what gets skipped. It is clear what the tool produces, though the operative verb is implicit ('Cut list of...') and it never explicitly distinguishes itself from siblings like 'joinery', 'layout', or 'export'.

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 statement of when to call this versus alternatives, nor any prerequisites. The only pointer toward another tool is the aside that 'export what=cut_list writes it as .csv, or .dxf/.svg', which names a mechanism rather than a decision condition. The dense output-format detail substitutes for usage guidance rather than supplying it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description goes beyond that by disclosing the atomic deletion semantics, the side effect of orphaning labels, the labels_left reply structure, and the rationale for index-code invalidation — real behavioral context not present in annotations.

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 main purpose is front-loaded, but the sentence is a long, em-dash-heavy run-on; the clause about an index code pointing at another piece being 'found by nobody' is confusing and could be trimmed. Structure is functional but not clean.

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 an output schema present, return values need not be re-explained, yet the description still characterizes the labels_left payload and the labels flag. It covers scope, atomicity and side effects; what remains thin is guidance on failure modes or partial-deletion behavior.

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%, so the baseline is 3. The description earns above baseline by explaining the consequence of labels=true (labels deleted in the same step) and clarifying that ids accept any element type, adding intent beyond the schema's field-level text.

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 (delete/remove) and concrete resources (walls, rooms, pieces, any element by id), plus the atomicity trait. It is unambiguous versus swap-style siblings like move or update, but it never explicitly differentiates itself from the edit_* family, which also mutate model elements.

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 only implied: the agent can infer when to set labels=true (to also purge dangling labels) from the explanation. There is no explicit when-to-use/when-not guidance or routing to an alternative tool, so this is minimum-viable rather than instructive.

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

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

Annotations already declare readOnlyHint and closed-world behavior. The description adds meaningful context by explaining what each action reveals (the active discipline, hidden elements, layers, grouped quantities) and reinforces that changes belong to edit_disciplines. No auth or rate-limit details, but the added return semantics are useful.

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 content is dense and informative but not optimally front-loaded; the first sentence is a fragment and the return shapes are embedded mid-description. It is reasonably efficient but could be structured more clearly for an agent scanning for the tool's purpose.

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 optional parameter, full schema coverage, annotations, and an output schema, the description provides enough context to call the tool correctly. It explains both actions and the alternative for mutation, though it does not elaborate on sibling differentiation beyond edit_disciplines.

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%, so the baseline is 3. The description goes further by detailing the two enum values: what 'active' returns (discipline, hidden state, layers) and what 'quantities' returns (grouped counts with names). This adds genuine meaning beyond the schema's brief 'Default active'.

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 identifies the resource (disciplines, plan layers) and explains what each action returns, distinguishing it from the mutating sibling edit_disciplines. The opening sentence is a noun phrase rather than a clear verb+resource, but the title and action breakdown make the read-only purpose evident.

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 explicitly points to edit_disciplines for changing what is shown, giving one clear alternative for mutation. However, it does not say when to choose this tool over other read siblings like show_plan, electrical, or plumbing, leaving usage largely implied.

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

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

Annotations flag a destructive, non-read-only edit, and the description goes well beyond that: it explains that anchor makes dimensions re-measure on every change, what happens to already-off dimensions ('comes back in left [[id, written, measured, near]]'), what happens when an anchor's piece is deleted, and that bake permanently converts automatic chains into editable dimensions. These are meaningful behavioral consequences the annotations do not carry.

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 body is one dense run-on block of poorly punctuated prose with embedded return-shape literals ('{dims,refs,details,legend,rooms:[[room,[[tag,...]]]]}') that is hard to parse and not front-loaded. Several clauses duplicate the per-parameter schema descriptions verbatim, so the text is not earning its length.

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?

The tool is complex (7 modes, mutation, output schema), and the description covers the destructive switches, the anchor lifecycle, and what the mode responses contain. With an output schema and annotations already present, the remaining gaps (no explicit when-to-use routing) are minor; completeness is largely satisfied.

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 description coverage is 100%, so the schema already documents all seven flags and the description largely restates them. It does add some nuance (renumber's reading-order behavior, the shape refs=true returns, legend/chains output formats), but much of this overlaps with the per-parameter schema text rather than extending it, so the baseline of 3 is appropriate.

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 verb+resource is clear ('Change the plan annotations') and the description enumerates the concrete facets it operates on: dims, refs, details, legend, bake, anchor. It also implicitly distinguishes itself from the read-only sibling with '`annotations` reads them.' It stops short of a crisp one-line scope statement, but an agent can tell what it does.

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 real conditional guidance for one mode ('tie them while the numbers are right' / 'Run it while the numbers are right'), and the pointer that `annotations` reads rather than edits. But for the other six switches (dims, refs, legend, details, renumber, bake) there is no when-to-use, sequencing, or alternative-selection guidance — usage is implied by the mode descriptions rather than stated.

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

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

Annotations mark it as destructive (destructiveHint: true) and not read-only, and the description reinforces that `trace` creates walls 'in one undo step' and `set` modifies the drawing. It also notes that `clear=true` removes the background. This adds useful behavioral context beyond annotations.

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 description is dense but front-loads the two actions. However, it crams many parameter details into a single run-on sentence, making it harder to parse. Some redundancy with schema descriptions.

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 18 parameters and a destructive operation, the description covers the key behaviors: scale calibration, undo step, and removal. It also refers to `render_plan` for checking. An output schema exists, so return values needn't be explained. The only gap is not explaining when to use this tool versus `background` or `edit_walls`.

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 description enumerates all parameters and their purposes, but the schema already has 100% description coverage for each parameter. The description adds value by grouping parameters by action and explaining defaults, but doesn't go beyond the schema substantially. Baseline 3, bumped to 4 for practical grouping.

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 clearly states two specific operations: placing a scanned plan under the drawing at real scale, and turning it into walls. It distinguishes itself from siblings by naming the `action` values and what each does. However, it doesn't differentiate from `edit_walls` or `background`, which may overlap.

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 implies when to use each action but doesn't explicitly state when to choose `set` vs `trace` vs alternatives like `background` or `edit_walls`. It only gives a hint to check with `render_plan`.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, covering the safety profile. The description adds convention context (yaw/pitch orientation, cm/degrees, 'missing values from the visitor' defaults) but never states that 'delete' permanently destroys a stored view or what happens to indices after deletion. Adequate but thin beyond the annotations.

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?

Highly front-loaded and dense, with no filler sentences; action semantics are packed into a compact block. The telegraphic style ('delete {i}. cm and degrees.') risks ambiguity, but every clause carries information.

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 10 parameters, a multi-value enum, and an output schema already present, the description covers all four action branches and the coordinate conventions well. Gaps are minor: no note on post-delete indexing or error behavior for invalid indices.

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% so the baseline is 3, but the description genuinely exceeds it: it maps which parameters belong to 'store', defines yaw 0 as +y/plan bottom and 90 toward -x, states pitch positive looks down, and specifies cm/degrees units and the default view name.

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+resource ('Change the points of view') and enumerates the four modes of operation (view, aerial, store, delete). It implicitly distinguishes itself from the read-only 'cameras' sibling by pointing to it for the list, though it never names the contrast in the purpose line itself.

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?

Enumerates each action and its effect, and explicitly routes the agent to the 'cameras' tool for listing. However, it gives no guidance on prerequisites (e.g., whether a view index must exist before delete) or when aerial is preferable to a stored view.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds substantial behavioral context beyond that—new symbols go to the selected discipline while the rest is dimmed, hiding removes items from the plan, its exports and the 3D, and the 3D follows the plan unless show_all_3d=true. This is exactly the operational disclosure a mutating toggle needs.

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 lead sentence is well front-loaded, but the body is a dense semicolon-heavy wall of text mixing actions, layers, 3D behavior and override mechanics, making it hard to parse. Information density is high, but structure and scannability suffer.

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 an output schema present, return values need not be explained, and the description covers the complex discipline/layer/3D interplay, including the update(layer=) override. It is nearly complete for this complexity, though the tangled presentation leaves some edge relationships (e.g., show vs. select on architecture) to inference.

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%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that d means a discipline for select but may also be a plan layer (lighting/appliances/joinery) for show/hide, and it enumerates what each layer contains. This disambiguates the overloaded parameter in a way the schema does not.

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 'Change what the plan shows' gives a specific verb+resource, and the text names what each action (select/show/hide) operates on, distinguishing disciplines from layers. However, the run-on phrasing and the mixed treatment of disciplines vs. layers make the core purpose harder to extract than a clean statement would, so it falls short of the top score.

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 explains the effect of each action (select vs. show/hide) and routes the agent to alternatives: update(layer=...) for overriding a piece's layer, and the 'disciplines' tool to see current state. What's missing is an explicit statement of when NOT to use this tool, so it stays at a clear-context, no-exclusions level.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false. The description adds real value beyond that: 'each action is one undoable step' (mitigating the destructive hint) and 'replacing the earlier run of the circuit' (spelling out what is destroyed). It also discloses the `route` return shape, which is unusual given destruction semantics.

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?

Front-loaded with purpose and every clause carries signal — no filler. However it is delivered as one dense semicolon-heavy paragraph covering five actions, which is harder to parse than the same content segmented by action; brevity is achieved at some cost to scannability.

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 21-parameter, five-action mutation tool with an output schema, the description covers every action, the conditional parameter mappings, and the destruction/undo model. Remaining gaps (permissions, failure modes, whether undo is guaranteed for every action) are minor against a rich schema and existing annotations.

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 description coverage is 100%, so the baseline would be 3, but the description adds cross-parameter logic the schema can't express: 'a 220 V outlet makes its circuit 220 V', 'on automation points it takes standby_w, on a dimmer max_w, on a panel modules', and the ids/circuit vs pts distinction. These conditional applicability rules are genuine added meaning.

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 ('Change the electrical and telecom project') and then enumerates the five concrete mutations (assign, voltage, cable, route, wifi). The resource is distinct from siblings like edit_lighting, edit_plumbing, edit_walls, so an agent can route here 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?

Gives strong internal routing: 'assign {ids, circuit}' vs. 'circuits {...} for the whole division', and 'with ids or circuit instead of pts it is a route', plus the fallback 'without via it takes the cheapest premise'. It even points to the `rules` topic=electrical for surface wiring constraints. It stops short of explicit when-not-to-use or sibling alternatives, so it earns a 4 rather than 5.

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

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

The annotations declare only the destructive/read-write profile. The description adds valuable behavior beyond that: undo/redo step through changes made by anyone, the reply names what changed, checkpoints persist with the project and survive saving, and revert preserves every id unlike duplication. This meaningfully improves the agent's understanding of side effects and results.

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 description is front-loaded with the action list and then explains the less obvious actions (checkpoint, revert). It is appropriately sized for a four-action tool, though the revert/duplication clause is somewhat dense and could be tightened.

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 has four actions, a 100%-covered schema, and an output schema, the description is nearly complete. It covers persistence, id preservation, and reply behavior, but does not explicitly warn that revert discards later changes or state whether checkpoints can be removed, leaving minor gaps for a destructive 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?

Schema coverage is already 100%, so the schema documents both parameters. The description still adds meaning by tying each action enum value to its effect (e.g., checkpoint remembers this point, revert undoes back to it while keeping ids) and clarifying how label is used. It does not add syntax or edge-case detail for the parameters.

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 four specific actions (undo, redo, checkpoint, revert) and explains what each does, including the alternate framing 'name where the plan is now and come back to it.' It also distinguishes this tool from the sibling history tool and from duplicating a version. This gives an agent a clear, distinct purpose.

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 explicitly points to `history` for listing checkpoints and contrasts revert with duplicating a version ('a copy renumbers'), which helps choose the right tool in those cases. However, it does not state general when-to-use or when-not-to-use guidance for undo/redo versus other edit tools, leaving some inference to the agent.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuinely non-structured behavior: omitted fields 'stay as it was' (patch semantics), `{key: null}` removes a property, and city/people are persisted with the project and inherited by ergonomics/layout/dry runs. That persistence vs per-call distinction is real added value.

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 enumeration of editable settings so the agent sees scope immediately. The second sentence is slightly meandering but earns its place by explaining why city/people matter. No filler sentences.

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 an output schema present, return values need not be described, and the safety profile is carried by annotations. The description covers the semantically rich parameters (properties, people, city) adequately. It under-describes the compass geometry and the region/country code-selection parameters, though the 100%-covered schema compensates.

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 description coverage is 100%, so the schema already documents all 11 parameters in depth, including the People and ReviewScope sub-objects. The description mostly restates what the schema carries (properties as {key: value|null}, the people fields, city=sao-paulo) and omits region, country, compass_d, compass_at and compass_visible entirely. Baseline 3 is appropriate.

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 specific operations on a specific resource: rename the project, set/remove properties, set the compass, set the city code, and set occupants. An agent knows this is the project-level settings editor. It does not, however, distinguish itself from overlapping siblings such as edit_levels (storey properties are set here too via `level`) or the `home` tool.

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 only implied: the trailing sentence about `ergonomics`, `layout` and dry runs hints that this is where project-wide context is established before scoring. There is no explicit when-to-use statement, no when-not to use it, and no named alternative among the many `edit_*` siblings.

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

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

Goes well beyond the annotations: delete removes a storey *and its content*, elev raises a storey *with its walls, floors and openings*, reference=true marks a tracing layer that *checks and ergonomics skip*. These are meaningful mutation consequences and side effects an agent needs, consistent with destructiveHint=true.

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?

Front-loads the purpose ('Change the storeys') then walks through actions compactly with shorthand notation. Every clause carries information; the brace notation is terse but not padded, though slightly cryptic to parse.

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 6-parameter mutation tool with an output schema, the description covers all actions, their parameters, destructive side effects, the reference-layer behavior, and the sibling listing tool. Nothing essential for correct invocation 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 100%, so the baseline is 3, but the description adds real value by mapping which parameters apply to which action (name/h/elev for add; id+elev/h/name/reference for update) and explaining the semantic effect of elev and reference. Adds meaning beyond the field descriptions alone.

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+resource (changing storeys) and then enumerates the four operations (add, select, delete, update) with their effects. It also clearly differentiates from the sibling `levels` tool by naming it as the list operation. An agent can distinguish this from other edit_* tools without opening the 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?

Explains when each action applies (e.g. use `reference=true` when two storeys share an elevation) and routes listing to the `levels` tool. It notes 'Other tools act on the selected storey,' implying selection is a prerequisite. No explicit when-not guidance against other edit tools, but context is clear.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: a version is immutable ('never changes after'), what payload is carried over (model file, companion files, reference pictures, measurements, unit, box, brand, source link), and what notes and fidelity record. This is exactly the disclosure a mutation tool needs.

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 operation and its scoping are front-loaded, and the em-dash-aside efficiently enumerates the preserved payload. It is a single dense sentence, slightly overloaded, but nearly every clause earns its place.

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 an output schema present, return values need not be explained, and the description covers what gets published, immutability, and the notes/fidelity semantics. It stops short of stating prerequisites or how this relates to the sibling library/update tools.

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 description coverage is 100%, so all five parameters are already documented, including notes ('what changed') and fidelity ('what was estimated'). The description restates those meanings in prose without adding format, constraints, or defaults the schema lacks, so the baseline 3 is appropriate.

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 opens with a specific verb and resource — 'Publish to the asset library' — and the action=publish phrasing pins down the exact operation, so an agent knows this creates a new library version. It does not, however, distinguish itself from siblings like library, update, or create, which publish-related work could plausibly route to.

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 or when-not-to-use guidance: nothing says to prefer this over update/create, nor what prerequisites (e.g. an existing piece id, a name collision policy) must hold. The trailing 'library lists them' is a behavioral note rather than routing guidance.

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

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

Annotations already declare a non-read-only, non-destructive, non-open-world mutation. The description goes further by explaining the placement mechanism, the termination condition, and what is returned (placed ids plus the room's rating before and after) — meaningful behavior beyond the annotations. It does not discuss reversibility or idempotency, but destructiveHint=false plus the reported ids cover the main risk surface.

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 dense sentence (plus a short follow-up on the reply), front-loaded with the action and the fixture enumeration. Every clause earns its place, though the semicolon-linked structure is slightly run-on.

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 full output schema and annotations covering the safety profile, the definition only needs to convey the mechanism and the target-setting behavior. It does that, plus notes the rating before/after. Adequate and complete for a four-parameter mutation 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?

Schema coverage is 100%, so the schema already documents all four parameters, and an output schema exists. The description clarifies that `lux` overrides the room reference and enumerates the valid `fixture` values, but this largely restates the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (fill), resource (a room with a grid of one fixture), the fixture options, and the termination condition (work plane reaching the ABNT/CIE reference or a given lux). That is far more concrete than the tautological title. It references the sibling `lighting` only as the photometry engine it shares, not as an alternative to choose between, so it stops short of a clean sibling differentiation.

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: this is the tool that auto-places a grid of fixtures to hit a target illuminance. There is no explicit statement of when to use it versus `lighting` (inspection) or `edit_electrical`, and no prerequisites or exclusions are given. The relationship to `lighting` is noted but not framed as a routing decision.

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

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

With annotations marking this as destructive and non-read-only, the description adds strong behavioral details: 'one undo step each,' revision refusal ('rev refuses a change if the plan moved on'), replacement preservation semantics ('keeping id, place, size..., finish, overrides and links'), and reply contents. These go well beyond the structured annotations.

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 description is information-dense but written as a long run-on sequence of clauses with semicolons, making it difficult to scan. It front-loads the core purpose, but the remaining action details are not structured for quick reference. It is adequate for a complex multi-action tool but not concise or well formatted.

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 25 parameters, six actions, destructive annotations, and an output schema, the description is complete enough for an agent to understand the tool's scope and side effects. It covers every action, preservation behavior, and revision handling, while the output schema can carry return-value details.

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 description coverage is 100%, so all 25 parameters are already documented in the input schema. The description restates much of that same information in prose and groups parameters by action, but it adds little semantic meaning beyond the schema itself. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Change the imported model of placed pieces (ids).' It distinguishes this tool from siblings by naming alternatives: 'model inspects; place imports.' An agent can tell this is the edit/mutation counterpart to inspection and import.

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 gives context for each action: replace swaps a file, material changes a material, part changes a part, lod adds a lighter file, reference keeps a photo, and measure keeps a measurement. It also names sibling alternatives at the end, though it does not state explicit when-not conditions. Clear usage context is present without formal exclusions.

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

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

Annotations already flag destructiveHint=true, and the description substantiates it: the new run 'replaces the earlier run of the same points and the lines drawn by hand to them (replaced_drawn)'. It further discloses refusal behavior (needs_depth_cm, why a premise can't be built), gravity/fall limits, and the reply payload — rich context well beyond the annotations.

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?

Purpose is front-loaded, but the body is a run-on wall of nested parentheticals and conditionals that is hard to parse on first read. Most sentences carry real information, yet the structure could be broken into clearer condition/behavior lines.

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 an output schema present, the description needn't spell out returns, yet it still sketches the reply shape. Combined with annotations covering the destructive profile, it is essentially complete — only the absence of usage exclusions/alternatives keeps it short of full marks.

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%, so the schema baseline carries most semantics; the description still adds value on defaults and constraints, notably the sewer `depth` meaning (free height under the finished floor, slab recess or storey-below void) and the 2%/1% fall rule tied to that parameter.

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 opens with a specific verb+resource: laying (routing) a pipe run of a kind (cold/hot/sewer/vent) in the plumbing project, and notes that `plumbing` reads it and `rules` topic=plumbing governs fittings. It distinguishes the routing action clearly from read-only siblings, though the core purpose is somewhat buried under dense conditional detail.

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 concrete applicability conditions: sewer runs only under the floor, by gravity, with specific falls; without `via` the cheapest buildable premise is chosen; an unbuildable one is refused with the reason. It also routes the agent to `rules` for fittings/refusals, but never states explicit when-not-to-use or a direct alternative tool for routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description still adds real context beyond them, notably that duplicate/new both auto-switch to the new version and that subsequent edits apply to the active version. It does not say whether delete is recoverable or what happens to the remaining versions.

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?

Front-loads the purpose, then enumerates actions in a compact per-action notation with no wasted sentences. The brace shorthand ({name?}, {i}) is terse to the point of being slightly cryptic, but it keeps the definition short and scannable.

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?

Covers all five enum actions, the active-version behavior, and points to the list tool, and an output schema exists so return values need no explanation. A mutation with destructiveHint=true could still note permission requirements or irreversibility of delete, but nothing essential for correct invocation 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 100%, so baseline is 3, but the description adds value the schema lacks: it binds each parameter to specific actions (i only for switch/rename/delete, name for duplicate/new/rename). Since all three params are optional, this action-to-argument mapping is the main thing preventing mis-invocation.

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 ('Change the plan versions (tabs)') and immediately disambiguates against the sibling 'variants' tool ('The list is the variants tool'). An agent can tell this is the mutation counterpart to variants without opening either 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?

Maps each action to its effect and required argument (duplicate {name?}, new {name?}, switch {i}, rename {i,name}, delete {i}), which tells the agent which call shape to pick. It also routes listing to the 'variants' sibling. It stops short of explicit when-not-to-use or precondition guidance (e.g. whether delete requires confirmation).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful action-specific effects: delete removes a keyframe, clear wipes the path, orbit replaces the path with an aerial tour, and render writes a Motion-JPEG file. It does not cover permissions or rate limits, but the destructive semantics are well surfaced.

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 description is compact and front-loads the core purpose before detailing actions. The semicolon-separated action list is dense but efficient; each clause carries operational meaning with little waste.

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 15-parameter tool with annotations and an output schema, the description covers all six actions, associated parameters, units, and key side effects. It stops short of explaining when to use this tool versus related render/video siblings, but it is otherwise complete enough for correct invocation.

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?

Although schema coverage is 100%, the description adds substantial meaning by grouping parameters by action, showing optional combinations like add {cam? | x?,y?,z?,yaw?,pitch?,fov?, i?}, render {path .avi, w?,h?}, and set {fps?,speed?}. It also states units (cm, degrees, m/s), which helps an agent invoke the action correctly beyond the schema descriptions.

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 clearly states that the tool changes or renders the video camera path, and it enumerates the specific path-editing actions (add, delete, clear, orbit, set, render). It does not explicitly differentiate itself from siblings such as video or render_3d, but the core purpose is unambiguous.

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 explains what each action does and which parameters belong to each action, effectively serving as invocation guidance. However, it does not state when to choose this tool over sibling tools like video or render_3d, leaving that comparison implicit.

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

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

Annotations only flag destructiveHint=true and readOnlyHint=false; the description goes far beyond by disclosing exactly what survives (longest wall keeps id, thickness, height, type, finishes), what is destroyed (other walls deleted), what is preserved (doors and windows), that gaps are closed, and what the reply returns. This is unusually rich behavioral disclosure for a destructive edit.

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?

Front-loaded with the two operations, then dense mode-specific detail. The middle sentence is long but each clause carries operative information (id retention, build preservation, deletion, openings, gap closing), so little is wasted.

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 an output schema present, the description needn't detail return structure, yet it still notes the reply names resulting ids. Combined with full parameter coverage and the destructive-behavior explanation, nothing an agent needs to invoke this correctly 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 100%, so the baseline is 3, but the description adds real meaning: t's 0..1 range and default 0.5 within the split action, and that ids for merge are ordered along the line they make. It does not restate id/action, but the added mode-specific semantics lift it above baseline.

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 pair and resource: 'Split a wall in two, or join walls into one.' No sibling tool competes for wall geometry, so an agent can route here unambiguously from the name plus first sentence.

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?

Explains the two modes and gives concrete merge scenarios (a wall a partition interrupted, a stretch imported as many segments, the same wall drawn twice), which tells the agent when merge is appropriate. It stops short of stating when NOT to use the tool or naming an alternative, so it does not reach 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavior beyond that: it spells out the return shapes for each action ({points, findings, pending, orphaned, sources}, the circuits row layout, wifi per-room dBm grades) and points to `rules` topic=electrical for check requirements. Return behavior is somewhat covered by the output schema, so not a full 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?

Dense, comma-spliced sentences with heavy domain jargon and parenthetical return-shape dumps run together. The action semantics are front-loaded reasonably, but several clauses would be clearer as a list, and some output detail duplicates the schema.

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 read-only review tool with an output schema and full annotation coverage, the description supplies enough: what each action evaluates, what the other paths are, and where requirements live (`rules` topic=electrical). Only the verbose, uneven structure keeps it from being fully complete.

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 description coverage is 100%, so all three params are already documented; baseline would be 3. The description compensates by explaining what each action actually returns and how `level`/`band` feed the wifi and per-storey views, adding meaning the schema does not carry.

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+resource: an electrical and telecom review against NBR 5410/NBR 16264, with the `check`/`circuits`/`wifi` actions named. It also explicitly routes mutations to the `edit_electrical` sibling, so the agent can separate it from neighbors. It stops short of a crisp one-line purpose, burying the intent in dense enumeration.

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 explicit when-to-use for each action (`check` default, `circuits` for load schedule/panel, `wifi` for coverage) and names alternatives for the other paths: changes go to `edit_electrical`, marking a finding goes to `accept`. It does not state any when-not-to-use exclusions, keeping it below a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with real substance: the host gets cut (including the wooden top of the cabinet beneath a sink), the item becomes part of the host and moves with it, and errors are actionable. It stops short of noting reversibility or permission requirements.

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 purpose is front-loaded and each clause is informative, but the middle sentence is a dense run-on of parentheticals and the error example ('use w = 61 no armário') is cryptic. It is not padded, yet it is harder to scan than it needs to be.

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 destructive, host-modifying operation the description covers the important effects (cutout/niche, cut_below, item joining the host) and even summarizes the reply shape despite an output schema existing. Nothing critical is missing, though auth/permission context is absent.

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%, so the baseline is 3, but the description adds genuine semantics the schema does not: the mutual-exclusivity/alternative between item (existing id) and cat (+w/d/h) for a new one, and how z positions the item. Only the at/dry nuances are left to the 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 names a precise verb+resource (embed an item into joinery with an exact fit) and enumerates the concrete cases: sink bowl/cooktop into a countertop, oven/microwave into a cabinet niche, TV onto a slatted panel. This is clearly distinguishable from generic siblings like place, move, or create.

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 spells out the scenarios in which embedding applies and how the item is supplied (existing id vs. new cat with w/d/h), which is strong contextual guidance. It does not, however, explicitly name alternatives (e.g. place/move) or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, and the description adds genuine context beyond them: 'It advises and never blocks', the meaning of `weight` (score gain if a finding is removed), how `fix` produces `move`/`update` arguments to apply and re-review, and that `accept` marks a finding as-drawn. It does not discuss rate limits or auth, but for a read-only advisory tool the behavioral picture is substantially 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?

Purpose is front-loaded effectively, but the second half becomes a dense inline dump of the return object's shape and field semantics that largely duplicates the existing output schema. Fully packed with information, yet the run-on clauses make it harder to parse than it needs to be.

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 an output schema present the description need not explain return values, yet the tool is complex (8 params, scoring model, tiers, fixes) and the description supplies the domain context an agent needs: what is scored, what 'advises and never blocks' means, and where to learn the scoring rules. Minor over-explanation of outputs is the only shortfall.

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 description coverage is 100%, so the baseline is 3. The description goes further by explaining that people and city supplied here weigh this call only (unlike `edit_home`), and by interpreting output fields such as `weight`, `fix`, `tier`, and `accept` — meaning that is not carried by the input schema's parameter descriptions.

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 — an ergonomics/habitability review of a home — and enumerates the concrete check areas (bed clearance, kitchen work triangle, wheelchair turning, etc.), so an agent knows exactly what it produces. It does not explicitly differentiate itself from siblings like `layout`, `electrical`, or `plumbing`, though the mention of `rules` topic=ergonomics partially routes the reader.

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?

Guidance is implied rather than stated: the contrast with `edit_home` clarifies parameter persistence ('People and city given here weigh this call only'), which helps an agent choose between a one-off review and a project-level update. There is no explicit when-not-to-use or a named alternative for the review itself among the many sibling review/edit tools.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds substantial behavior beyond that: the six format targets, A3 sheet sizing, scale semantics, and defaults. It never states that an existing file at `path` is overwritten, which is the one behavioral fact an agent would want for a destructive write.

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 operative clause ('Export to a file, by its extension') is front-loaded and the remainder is dense but purposeful, one sentence per `what` branch. The semicolon-chained extension lists are readable but slightly cluttered.

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 an output schema present, return values need no explanation, and the description fully covers both enum branches, all format options and their parameter dependencies. The only meaningful omission is overwrite/error behavior for the written file.

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% (baseline 3), and the description goes further by binding parameters together, e.g. `path`'s extension determines the format, scale only applies to plan/.pdf with ''omitted fits the sheet'', and h/w are png-only. This adds cross-parameter meaning the per-field schema text does not convey.

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 (export) plus the exact resource set (plan drawing/3D model, joinery cut list) and the mechanism (extension picks format). It is clearly distinguishable from siblings like render_plan, show_plan and cut_list, which produce views or data rather than files.

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?

Explicitly maps each `what` value to its valid extensions and what each format is for (pdf A3 with scale, svg true scale, glb/obj model, csv/dxf/svg sheets), which is real usage guidance. It does not, however, say when to prefer export over sibling tools such as render_plan or show_plan.

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

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

Goes well beyond the annotations by disclosing data handling ('Kept on this machine and, while the user's telemetry is on, sent to the project') and the response shape ('Reply {kept, sent}'). It also reveals a schema-invisible behavioral rule: although required parameters is 0, 'Every part is required,' and it warns that a vague note gets fixed in a way that breaks working behavior.

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?

Front-loaded with the core action, and the dense paragraph largely earns its length by listing triggers, the completeness rationale, the required-field enumeration, kind/tool, and data handling. Some flourishes ('the whole case', 'shortened the way') add rhetorical weight without much information, so it is not maximally tight.

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 9-parameter reporting tool with an output schema, the description covers everything an agent needs: purpose, triggers, required fields, the kind enum's meaning, the destination of the data, and the return values. Nothing material is left undocumented.

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% so the baseline is 3, but the description adds genuine meaning beyond the schema: it asserts all nine fields are required despite required=0, and clarifies intent for ambiguous fields ('must_keep ... "none known" is an answer', 'expected ... the reference the fix will be checked against'). It mostly restates field intent rather than adding new syntax or format rules.

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 ('Report to the developers what a tool could do better') and is unmistakable against every sibling, which are all domain tools (measure, render_3d, edit_walls). An agent can tell instantly this is the meta-channel for filing a structured complaint about another tool.

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 names concrete triggers for use — 'a reply that answered less than was asked, a detour, a wrong conclusion reached before the right one, a fix that would distort the plan, something missing' — and ties it to the moment it happens ('as it happens'). There is no explicit when-not-to-use, but no sibling offers overlapping function, so alternatives are not a real gap.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value by disclosing that both new and open replace the current project 'in place of this one', clarifying exactly what is destroyed. It does not mention undo or save side effects, but goes meaningfully beyond the annotation.

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?

Front-loaded with the general purpose, then scoped per-mode with terse 'new:'/'open:'/'save:' prefixes. Info-dense with no wasted sentences, though the run-on style compresses several rules into one sentence.

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 values need no explanation, and all three modes plus path rules are covered. Nothing essential to correct invocation is missing, though permissions/undo context would have been a bonus.

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%, so baseline is 3, but the description adds semantics beyond the schema: path accepts .newera or .sh3d-to-import for open, and is optional for save once previously saved. This is genuine added meaning.

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 clear verbs (start/open/save) and resource (the project), and enumerates each of the three action modes with specifics like '.newera' and '.sh3d' import. It does not explicitly contrast against siblings such as create or export, so it falls short of a 5.

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?

Implicitly guides usage per mode ('path is optional once it was saved' tells the agent when path can be omitted), but gives no when-to-use-vs-alternatives or exclusions relative to sibling tools. Adequate embedded guidance, no explicit routing.

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

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

Annotations already declare destructiveHint=true and non-read-only, so the modification profile is covered. The description adds genuine context beyond annotations: the pieces keep following the roof when it changes, and the change lands in the same undo step, with 'off' reversing the persistence. It stops short of spelling out permission or auth requirements, but the behavioral traits it does add are valuable.

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?

Front-loaded with the core action and its outcomes, then the persistence and undo behavior. It is dense but every clause earns its place by describing a distinct effect; the parentheticals make it slightly run-on but not wasteful.

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 an output schema present, return values need not be explained, and the description still notes 'Reply ok with the count'. It covers the geometry outcomes, the persistent-following behavior, the undo grouping, and the disable flag, leaving only minor gaps like explicit auth/permission needs.

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 description coverage is 100%, so all three parameters (ids, off, above) are already documented in the schema, giving a baseline of 3. The prose clarifies the 'off' flag in behavioral terms ('stops that', heights stay), but adds nothing about 'ids' or the 'above' threshold beyond what the schema states.

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 (Fit) and resource (walls, glass, panels) plus the concrete outcomes: a wall gets a sloping top and is split at the ridge, a panel becomes a triangle or trapezoid, slats get cut to the roof line. This is far more than a restatement of the name and lets an agent predict the geometric result 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 clearly signals when to use it (walls/pieces sitting under an A-frame or shed roof) and the inverse condition via 'off stops that'. It does not name an alternative sibling tool, but no obvious competing fit operation exists among the siblings, so the guidance is adequate though not exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context — that a checkpoint is project-scoped and survives saving — which is useful persistence information, but nothing about ordering, limits, or whether checkpoints expire.

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 no filler, and the resource identity is front-loaded. The '[label, changes ago]' shorthand is compact but slightly cryptic in isolation.

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 zero-parameter, read-only list tool with an output schema present and annotations covering the safety profile, the description supplies everything needed: what it returns and how checkpoints relate to `edit_history`.

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 the baseline is 4. The description's mention of the returned row shape adds a little framing but there is no parameter surface to document.

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 the resource (checkpoints) and its origin (`edit_history`), and the title supplies the verb 'List'. An agent can tell this is a read of previously remembered checkpoints rather than a creation tool, though the sibling relationship is only 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?

Usage is only implied: the mention of `edit_history` hints that this is the read-side counterpart, but there is no explicit 'use this when...' or 'use X instead when...' guidance. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. Beyond that the description discloses real behavior: every element carries bounds and faces, ids share one never-reused counter per version, and ndjson streams one element per line. It adds no auth or rate-limit notes, but the domain semantics are genuinely informative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.