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

The description discloses the mutation and destructive nature beyond annotations: it is 'one undoable step', it stops counting, and prune drops orphaned acceptances. It also describes the response format (accepted and removed counts) and advises re-reading the review. This aligns with destructiveHint=true and adds valuable context.

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 well-structured: it starts with the main action, explains prune, notes undoability, and specifies the response. Every sentence contributes, though it is slightly longer than strictly necessary. It is 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?

For a mutation tool with two parameters and an output schema, the description covers all critical aspects: effect on findings, prune behavior, undoability, and how to verify (read the review again). It is complete enough for an agent to invoke correctly without further assumptions.

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%, and the schema already explains both parameters (accept format and prune behavior). The description largely repeats this information without adding new semantic detail. Baseline 3 is appropriate since 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 clearly states the tool's purpose: to mark findings from specific review types (check_layout, ergonomics, electrical, plumbing) as looked at. It distinguishes itself from sibling tools by naming the exact review types and the effect (stopping counting).

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 explains the behavior in detail (stops counting, empty reason takes back, prune for orphaned findings) and notes the undoable step. However, it does not explicitly contrast with alternatives like delete or undo, nor does it state when not to use it. The guidance is implied rather than explicit.

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, so the safety profile is covered. The description adds valuable behavioral context: stale=true lists rows with a specific shape, checked counts what was compared, unverified lists sizes nothing can confirm, and the warning that 'an empty list with nothing checked is not a clean plan.' It also discloses the fallback note-checking behavior (a note standing on a piece or beside a single piece that shares a number is checked). This goes beyond the annotations without contradicting them.

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 every sentence earns its place: it covers the stale mode, checked counts, unverified lists, the note-checking rule, q= search, the no-args schedule, and the sibling edit_annotations. It is front-loaded with the core purpose ('Plan annotations, read') and then details modes. It is long, but the complexity of the tool justifies the length; no filler or repetition.

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 tool with an output schema, the description is remarkably complete. It explains all three invocation modes (stale, q, no-args), the exact row shapes, the meaning of checked and unverified, the note-checking fallback, and the relationship to edit_annotations. The output schema covers the schedule structure, so the description doesn't need to repeat it. An agent has everything needed to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaning beyond the schema: it explains what stale=true returns (rows [id, written, measured, against, text]) and what q= does ('searches label text on every storey'), plus the regex variant. It also clarifies the no-args mode returns the schedule. This is more than the baseline 3 for full schema coverage.

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' and then enumerates exactly what the tool does: lists stale dimensions/notes, checks counts, lists unverified sizes, searches label text, and returns a schedule. This clearly distinguishes it from sibling tools like edit_annotations (which 'turns modes on and off, ties dimensions and bakes chains') and update (which sets piece properties).

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 explicit when-to-use guidance: 'run it after moving geometry, before handing the plan over.' It also explains the modes (stale, q, no-args) and contrasts with edit_annotations, which is the sibling that modifies annotations. The q= and re: syntax is fully specified, so an agent knows exactly when to invoke this read tool versus a write tool.

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, so the mutation risk is known. The description adds valuable behavioral details beyond that: 'flip' turns a piece back to front and 'rebuilds what is inside it', 'mirror only swaps left and right and leaves the front where it was', and each sub-action has specific side effects. It also discloses the return value ('Returns new ids'). This goes well beyond the basic 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 long (about 150 words) but packs a lot of information for a tool with 9 sub-actions and 16 parameters. It front-loads the overall purpose ('Arrange elements in one undo step') and then lists each action in a structured, semi-colon-separated format. No sentence is wasted, though the density requires careful reading. It could be slightly more concise by grouping, but it stays efficient.

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 tool this complex, the description covers each action's parameters and behavior, plus the return value. It does not cover edge cases or prerequisites (e.g., whether ids must be on the same level, coordinate system assumptions), but given the output schema exists and annotations cover safety, an agent can invoke it correctly for the listed scenarios. The main gap is a lack of examples or warnings about interactions between actions, but it is sufficient.

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 every parameter is already documented. The description adds meaning by explaining how parameters drive each action, e.g., 'array {ids,n,dx,dy,dz} adds n copies stepping by dx/dy/dz cm' and 'align {ids,axis,edge:low|middle|high,value} lines pieces up by an edge'. It clarifies the purpose of 'edge' values (low=middle=high) and 'value' as the target coordinate, which goes beyond the schema's terse field names.

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 clear, multi-purpose resource: 'Arrange elements in one undo step' and enumerates each sub-action with its verb and resource ('array' copies pieces, 'align' lines up edges, 'distribute' sets them side by side, etc.). It explicitly distinguishes from sibling tools by detailing unique behaviors like 'flip' (turn a piece back to front) and 'front/back' (draw rooms on top/underneath), so an agent can select 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?

The description explains what the tool does but not when to prefer it over alternatives. It never mentions sibling tools like 'move', 'place', or 'joinery' or gives conditions for using those instead. The atomic 'one undo step' hint is useful, but the guidance is implicit rather than explicit about alternative selection.

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 description openly discloses that the tool 'Replaces the cabinets already there (keep ids stay)', which aligns with the destructiveHint annotation. It also goes beyond annotations by describing the placement algorithm, output shape, and dry-run behavior, giving the agent a realistic picture of 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?

The core purpose is front-loaded, but the rest is a dense, run-on sentence with a long parenthetical and many clauses. It contains valuable details, but the lack of sentence breaks and the overloaded structure make it harder to parse than it should 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 complex, destructive tool with 8 parameters and an output schema, the description covers the key behavioral rules, default dimensions, output format, and the joinery follow-up path. It is not perfectly clear on the dry-run semantics, but overall it gives enough context for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: default module widths (target=60, max=90), sink/cooktop widths, the role of p.sink/p.cooktop in placing cabinets and cutouts, and the meaning of 'keep' for preserving existing cabinets. This goes beyond simply restating parameter names.

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 phrase 'Fill a wall with cabinets sized for it' states a specific verb, resource, and intent, and the description immediately elaborates with measurable behavior (measuring free stretches, splitting modules, adding countertops, etc.). It is distinguishable from generic tools like 'place' or 'arrange', though it does not explicitly name a sibling alternative.

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 its use case clearly, and it does mention 'Change one module afterwards with joinery id' as a follow-up alternative. However, it does not explicitly state when to prefer this tool over siblings like 'arrange', 'place', 'update', or 'joinery', and the 'dry plans only' phrase is ambiguous.

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, so the agent knows this is safe. The description adds useful behavioral context beyond the annotation by specifying the return format: active is visitor|aerial, rows contain i,name,x,y,z,yaw,pitch,fov, and units are cm and degrees. No contradictions with 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 one compact sentence that front-loads the core information and provides structure and units immediately. It wastes no words and even includes a pointer to the relevant sibling tool. This is appropriately sized for what is essentially a no-input, list-returning tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, an output schema already present, and read-only annotations, the description covers the remaining gaps: the data shape, units, and the mutation alternative. There is nothing an agent needs to invoke this tool correctly that 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?

There are no parameters, so the schema carries no burden. The description adds semantic value by explaining the meaning of the output values (cm and degrees) and the active field's allowed values. This is the baseline for zero-parameter tools and slightly better because it pre-explains the response fields.

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 title 'List points of view' supplies the verb, and the description identifies the resource ('Stored points of view') and the exact payload shape. It distinguishes this from its sibling edit_cameras by explicitly naming it as the modification path. However, the description itself is a noun phrase rather than a verb clause, so it relies on the title for the action.

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 the usage context: to view stored points of view, call this tool; to change them, use edit_cameras. This routes the agent to the correct sibling for mutation, but it doesn't state additional conditions like when not to use it or prerequisites. Still, for a simple list tool with zero parameters, the guidance is sufficient.

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, so the description doesn't need to repeat that. It adds valuable behavioral context beyond annotations by explaining the meaning of the 'front' field (wall/free semantics) and the scope=project behavior of listing existing plan items. This enriches the agent's understanding without contradicting 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 a single dense paragraph that is front-loaded with the core purpose ('Find catalog items') but then packs a lot of detail about row format, front semantics, and scope behavior. All content is relevant and earns its place, but the density makes it less concise than ideal. It could be split into clearer sections.

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 and annotations covering the read-only hint, the description provides additional context on data semantics (front field) and the scope mode, making it fully complete for correct invocation. There are no missing details an agent would need to call the tool appropriately.

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 adds extra meaning for the scope parameter, explaining it lists existing plan items including imported models, which is not fully captured in the schema. It also clarifies the output field semantics (like front), indirectly aiding parameter use. This exceeds the 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?

The description clearly states 'Find catalog items' with a specific resource and then details the output row format. It distinguishes this from placement or other tools by focusing on search and listing. The verb and resource are explicit, and the scope=project mode further differentiates a special use case.

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 explicit guidance on when to use scope=project: to match a new piece to what the plan already uses, avoiding reintroducing generic items. It also implies the default mode for generic catalog search. While it doesn't name alternative tools, it gives clear context for the two modes, which is sufficient.

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?

Beyond the readOnlyHint annotation, the description discloses classification semantics, exemptions (e.g., compact countertop objects), limitations ('does not certify sash operation or ventilation', 'Hidden ceilings and unknown uncovered slopes are not inferred'), and special cases such as accepted/orphaned findings. It also clarifies behaviors like no_door only being reported once the storey has doors somewhere. This is far richer than the annotation alone.

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 single dense, unstructured paragraph mixing output taxonomy, edge cases, related-tool behavior, and parameter notes. It would be far more usable with bullets, sections, or a clear 'returns' framing. Despite being information-rich, it is not appropriately sized or structured for quick agent consumption.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the many distinct problem categories, the description is exceptionally complete: it defines every reported kind, explains field semantics, gives examples, states conditions and exemptions, documents parameter behavior, and even covers interactions with the accept tool. The presence of an output schema lowers the burden for return-value details, and the description still covers them thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters already have descriptions, so the baseline is 3. The description adds marginal meaning by noting that `areas` compares room areas against the reference drawing and that `level` defaults to the displayed storey. That extra context lifts it slightly 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?

The title supplies the verb+resource ('Check the layout') and the description enumerates the specific layout problems the tool reports, so an agent can tell this is a layout diagnostic. However, the description opens with a bare list ('Layout problems: ...') rather than an explicit declarative sentence, and it never contrasts itself with related diagnostics like measure or checkpoints.

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 provides no explicit guidance about when to call this tool instead of alternatives such as measure, ergonomics, or checkpoints. It implies usage through its exhaustive problem list and boundary conditions, but it never states 'use this when ...' or names a preferred alternative.

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, and the description adds meaningful context: reverting keeps every ID, checkpoints persist with the project and survive saving, and the 'checkpoints' tool can list them. It does not fully specify all side effects of reverting, such as what happens to later checkpoints, but it goes beyond the structured annotation 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 description is three dense sentences with no filler. The purpose is front-loaded, the action semantics follow, and the persistence/listing detail is useful rather than redundant. Every sentence 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?

For a two-parameter tool with 100% schema coverage and an output schema, the description covers purpose, actions, persistence, and the key ID-preserving benefit. The main gap is that 'undoes back down to it' is somewhat vague about exactly what gets discarded on revert, but the destructiveHint annotation partially covers that.

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%, and the schema already documents both parameters including the default/revert behavior of 'action'. The description confirms that {label} is required by both actions and shows usage syntax, but it adds little semantic value beyond the input 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 clearly identifies the resource (the current plan state) and the two operations: remembering a point via 'checkpoint' and undoing back to it via 'revert'. It is unambiguous about what the tool does, though it does not explicitly differentiate it from sibling undo/redo tools.

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 states that 'checkpoint' is the default action and explains when to use 'revert', and it contrasts checkpointing with duplicating a version to justify why checkpointing preserves IDs. It lacks explicit guidance on when not to use this tool versus undo/redo, but the action-level guidance 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 already declare readOnlyHint=true, so the read-only nature is covered. The description adds genuinely useful behavioral context beyond annotations: checkpoints are project-scoped and survive saving, which tells an agent about state persistence. No contradictions with annotations are present.

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 two short sentences with no filler. It front-loads the output format ('rows [label, changes ago]') and then adds a meaningful behavioral fact about persistence. Every sentence 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?

For a zero-parameter, read-only listing tool with an output schema, the description covers the essential shape of the result and the persistence behavior. It is slightly cryptic in phrasing and does not mention usage context, but the tool's simplicity and annotations make it adequately 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter information for the description to add. With 0 parameters, the baseline of 4 applies, and the description correctly avoids inventing irrelevant parameter details.

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 title and tool name make clear this is a listing operation ('List checkpoints'), and the description confirms the resource by describing what a checkpoint is and what its rows contain. It does not explicitly name or distinguish itself from the sibling tool 'checkpoint', so it stops short of full 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?

The description gives no guidance on when to use this tool versus alternatives such as 'checkpoint' or 'undo'. The persistence note ('survives saving') lightly implies a use case, but no explicit when/when-not conditions or alternative tool routing are provided.

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=false, so the agent knows this is a write operation. The description adds valuable behavioral context: 'in one atomic step' signals that all elements are committed together, and it explains key behavioral nuances like ceiling_flat=false following wall profiles, gables=true closing ends, and skylights cutting glazed openings. This goes beyond what annotations provide.

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 single dense sentence that front-loads the main verb and resource list, then packs parameter semantics into parentheticals. It's efficient but slightly long and could be easier to parse; the parenthetical-heavy structure makes it dense. Still, every clause earns its place and there's no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, 8 element types, nested specs), the description covers the key decision points: how to specify walls, rooms, roofs, and solids, and the atomicity guarantee. The output schema exists, so return values don't need explanation. It doesn't mention error cases or prerequisites, but for a create tool with this breadth, the coverage is strong.

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 adds meaning beyond the schema by explaining the purpose of each element type and key parameter interactions: hs per point for gables, at=[x,y] to detect rooms from walls, ceiling_flat=false following wall profiles, pitch or ridge_h for roofs, and profile [[u,z]] swept from a to b for solids. This is genuinely additive, not just restating 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 opens with a specific verb ('Create') and enumerates the exact resources: walls, rooms, dims, labels, roofs, and solids. It distinguishes itself from siblings like 'trace_walls' and 'merge_walls' by covering the full creation surface in one atomic step, and the title 'Draw walls, rooms and more' reinforces the scope.

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 this tool: when creating any of the listed element types in one atomic step. It doesn't explicitly name alternatives or exclusions, but the sibling list (trace_walls, merge_walls, split_wall, place) makes the boundary clear enough. A 4 is appropriate because the context is clear but no explicit when-not-to-use guidance is 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?

With readOnlyHint=true already provided, the description carries a low safety burden and instead adds substantial behavioral detail: the 50 mm thickness rule, board finish and thickness semantics, no edge banding, skipped parts handling, merging criteria, and MDF/MDP material definitions. This goes well beyond the annotations and gives the agent a rich model of the tool's 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 information-dense and front-loads the core subject, but it is structured as a long run-on sentence with several parenthetical asides. The MDF/MDP material details, while useful, could be separated or moved without losing clarity. It is thorough at the cost of 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 fairly complex domain, the description is remarkably complete: it covers input scope, board derivation rules, row format, merging behavior, export alternatives, and material standards. The output schema likely covers return values, and the annotations cover read-only safety, so nothing essential for correct invocation appears 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?

The input schema already covers the only parameter, ids, with a clear description of valid values and default behavior, so schema coverage is 100%. The main description adds domain context about what drawn groups and builds are, but it does not add direct parameter-level guidance such as id formats or selection constraints. 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 identifies the resource clearly: a cut list for joinery builds and hand-drawn groups, and it distinguishes cut_list from export_cut_list by stating that the latter writes the list to file. However, it lacks an explicit verb like 'returns' or 'computes', leaving the exact action somewhat inferred 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?

The description gives useful usage context: it applies to builds and drawn groups, defaults to all such groups on the storey, and points to export_cut_list for CSV/DXF/SVG output. It does not explicitly enumerate when to prefer this over other siblings, but the relationship to export_cut_list provides a clear distinction.

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 description adds significant behavioral context beyond the annotations: it mentions the atomic nature of the deletion, the side effect of left-over labels being reported (labels_left), and the option to delete those labels in the same step. This is valuable. The annotations already indicate destructiveHint=true, so the description doesn't contradict that, but it provides more detail.

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 concise and front-loaded with the core action (delete elements by id, atomically). It then explains the edge case with labels. The writing is efficient, though the phrasing around 'labels_left' is a bit dense and could be clearer, but it doesn't waste words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (deletion with side effects) and the rich output schema (which likely includes labels_left), the description covers the key points: atomic deletion, handling of orphaned labels, and the option to delete them. It does not explain return values in detail, but that is covered by the output schema. No major missing information.

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 schema coverage is 100%, and the schema already describes both parameters (ids and labels). The description does add a bit of meaning by explaining the behavior around labels (e.g., how labels_left works and the effect of labels=true), but it doesn't add much beyond that. The schema is already clear on parameter types and descriptions, so the description adds only marginal value.

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 the tool deletes elements by id, atomically, and covers the types of elements (walls, rooms, pieces, dimensions, labels, lines). It distinguishes itself from siblings like 'update' and 'move' by focusing on deletion. However, it could be more explicit about the meaning of 'atomically' and the exact scope of deletion.

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 clearly states when to use the tool: when elements need to be deleted by id. It also implicitly suggests that labels can be deleted as part of the same operation (via the 'labels' parameter), but it doesn't explicitly contrast with alternatives like 'edit_annotations' or 'update' for modifying elements. The guidance is clear for deletion tasks but doesn't provide 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 mark the tool readOnly, and the description is consistent, adding semantics about the active/hidden/layers structure and how quantities are grouped by catalog kind. It does not go into auth or error behavior, but the read-only safety profile is already covered by 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 content is information-dense but the opening sentence is fragmented ('Electrical and plumbing projects and plan layers over the plan') and the return shapes are spelled out even though an output schema exists, making it longer than necessary. The use of labeled inline blocks does aid 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?

For a simple read-only query with one optional parameter and an output schema, the description covers the available actions and points to related tools for mutations and per-piece data. Minor ambiguity in the opening sentence keeps it from a 5.

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 already defines `action` with 100% coverage, so baseline 3; description adds the default `active` behavior and clarifies what each action returns, which helps the agent select a value. Not a 5 because it doesn't specify string casing or validation beyond 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 intended function is inferable: this is a read-only query for discipline display state and quantities. It names two modes and contrasts with edit_disciplines and get_home, though the opening sentence lacks a clear verb and is grammatically incomplete.

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 documenting the two `action` modes and directs mutation to edit_disciplines and per-piece layer lookup to get_home. It does not explicitly state when not to use this tool, but the exclusions are 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?

Despite destructiveHint=true being present, the description goes far beyond it: it discloses that anchor ties dimensions to current geometry and re-measures them on every change, that tags persist with a piece and leave gaps when removed, that dead anchors are re-tied or released, and that bake turns automatic chains into editable dimensions. This gives the agent a strong model of side effects and persistence.

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 single dense, run-on block with nested clauses and parentheticals that are very hard to scan (for example, the anchor sentence and the long refs/legend sentence). While the content is relevant, it needs bulleted modes and clearer separation to be efficiently parseable by an agent.

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 multi-mode destructive tool with seven switches, the description covers the essentials: prerequisites for anchor, behavior on stale or deleted anchors, return shapes for modes, renumbering semantics, and the relationship to the annotations read tool. The output schema exists, so the detailed return-value prose is bonus rather than a required gap.

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 schema already covers all seven boolean parameters, but the description adds real semantics: what each switch returns (e.g. chains [[from,to,cm]] for dims, symbols {discipline:[[name,count]]} for legend), what refs=true returns, and what renumber/bake do to tagging and dimension state. This is far beyond the baseline for fully covered schemas.

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 the plan annotations' names a specific verb and resource, and the closing sentence 'The annotations tool reads them' explicitly separates this mutating tool from its read-only sibling. The different modes (anchor, dims, refs, legend, bake) all fall under the single purpose of changing plan annotations, so an agent can tell what the tool is for.

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 mode-level conditions, such as 'run it while the numbers are still right' for anchor and 'renumber=true numbers them again in reading order', and points to the annotations tool as the reader. But it never states directly when to choose edit_annotations over the sibling edit_* tools or when not to use it, leaving much of the selection 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 mark the tool as destructive and not read-only, and the description reinforces this by exposing the 'delete {i}' operation. It adds valuable behavioral context beyond annotations: units (cm and degrees), coordinate conventions (yaw 0 toward +y, pitch positive down), and that missing store values come from the visitor. This is strong supplementary transparency.

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 and information-rich, with every clause contributing operational detail. It is somewhat run-on and mixes commands with coordinate conventions, but it remains compact and front-loads the core purpose before the details.

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 10 optional parameters, an output schema, and annotations, the description covers all necessary operational aspects: the four actions, parameter units, coordinate system, default behavior for missing values, and the sibling tool for listing. An agent has enough context to invoke the tool correctly across its main use cases.

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 meaningful semantics beyond the schema: it explains the action subcommands, unit conventions, yaw/pitch orientation, and that look_at sets yaw and pitch. This helps an agent use the parameters correctly without guessing coordinate meanings.

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 clear verb and resource: 'Change the points of view' and enumerates the four concrete operations (view, aerial, store, delete). It also differentiates itself from the sibling 'cameras' tool by explicitly saying 'The list is the cameras 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?

The description gives clear context for when to use the tool: to show, store, or delete stored views, or return to orbit view. It explicitly points to the 'cameras' tool for listing views, which is a useful alternative. It does not exhaustively discuss exclusions versus other sibling tools, but the main routing 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses what gets dimmed or hidden, how exports and 3D are affected, and how show_all_3d modifies behavior. This is substantive context that goes beyond the structured annotation 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 description is a single dense, run-on paragraph mixing multiple actions and referencing 'update' in a confusing way. It lacks bullet points or clear separation of concepts, making it longer and harder to parse than necessary.

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 description covers behavioral effects well, but it introduces confusion with 'update' and does not address prerequisites or failure conditions. Since an output schema exists, return values need not be explained, but the applicability of the tool could be clearer.

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 adds real value by explaining the practical effects of each d and action value, listing example items per layer, and detailing show_all_3d interactions—going beyond the schema's short 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?

The opening 'Change what the plan shows' states a clear verb+resource, and the description elaborates on select/show/hide behaviors. It doesn't explicitly contrast with sibling tools like show_plan, but the core purpose is clear.

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 usage through examples (select architecture hides electrical/plumbing, show/hide layers) but gives no explicit guidance on when to prefer this tool over alternatives. The mention of 'update' as a layer override is not framed as a when-to-use comparison.

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?

Beyond the destructiveHint annotation, the description discloses extensive behavioral details: writes circuits, draws cables, replaces earlier runs, refuses routes that cannot reach points, and lists refusal conditions (e.g., via=tape refused over rating, in bathrooms). It also describes side effects like replacing drawn cables and provides output details for route actions. These go far beyond the annotation and give the agent a precise model of what the tool will do.

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 single dense wall of text covering six sub-actions with semicolon-separated clauses. It is not concise, and the lack of bullet points or clear sections makes it harder for an agent to scan. However, every sentence carries substantive information, so it is not redundant. Given the tool's complexity, a score of 3 reflects the poor structure relative to the potential for clearer organization.

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 description is remarkably complete for a tool of this complexity. It covers all sub-actions, their parameters, behavioral side effects, refusal conditions, and output descriptions for route. An output schema exists, so return values are already specified. Nothing essential for correct invocation appears missing, making this a complete reference for an agent.

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?

While the schema has 100% coverage with per-parameter descriptions, the description adds rich inter-parameter semantics: it explains how `circuit` and `circuits` relate, how `via` affects routing, how `pts` vs `ids`/`circuit` changes cable vs route behavior, and how `volts` interacts with `assign`. It also documents defaults (e.g., cat6 default, cheapest via when omitted) and conditions (e.g., sockets require earthed tape). This is far more than the schema provides, earning a 5.

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 'Change the electrical and telecom project', which is a specific verb + resource. It then details multiple sub-actions (assign, voltage, cable, route, wifi) that clearly distinguish this tool from siblings like edit_plumbing and edit_cameras. It also explicitly contrasts itself with the 'electrical' read tool, making its purpose and scope 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?

The description implies the tool is for writing while 'electrical' is for reading ('the electrical tool reads it'), providing a clear usage context. It does not, however, explicitly enumerate alternatives or state when not to use this tool (e.g., for plumbing or camera edits), which would earn a 5. The guidance is implicit rather than explicit, so a 4 is appropriate.

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?

Discloses side effects beyond the destructiveHint annotation: delete removes content, add selects the new storey, update with elev raises walls/floors/openings, and reference layers are skipped by checks and ergonomics. This adds meaningful behavioral context beyond the simple mutation flag.

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?

Compact and dense, front-loading the purpose and then covering each operation in a single line. The reference explanation is slightly verbose but directly useful. No filler or redundant phrasing.

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 four actions and all six parameters, explains the selection side effect, and points to the levels tool for listing. With an output schema present, it provides sufficient context for correct invocation without needing to describe return values.

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?

Though the schema documents all parameters at 100%, the description adds action-dependent semantics: add takes name?/h?/elev? and selects; update takes id plus optional elev/h/name/reference with specific behaviors for each. This clarifies parameter combination per action, which the schema alone 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?

States the verb 'Change' and resource 'storeys', then enumerates four distinct operations (add, select, delete, update) with their parameter patterns. It explicitly differentiates from the sibling 'levels' tool by saying 'The list is the levels tool,' making the purpose 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?

Provides clear context on selection: 'Other tools act on the selected storey.' Also explains when to use the reference flag: 'which is what you want when two storeys share an elevation.' Points to levels for listing. Does not explicitly exclude alternatives but gives situational guidance for the key decisions.

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 description fully discloses the destructive nature of the operation: it replaces the earlier run and lines drawn by hand, and it can refuse a run with a reason. It also details sewer behavior (gravity, fall percentages, depth requirements, refusal conditions) and the exact reply object, which goes well beyond the destructiveHint=true 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?

The description is dense and information-rich, with the core operation front-loaded and the sewer-specific rules appended after a clear transition. It is long, but nearly every clause adds a necessary constraint or output detail; only minor redundancy with the schema keeps it from a 5.

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 complex domain-specific tool, the description covers the route syntax, defaults, material lists, failure modes, and sewer constraints. The output schema exists, so the described reply format supplements it without needing to duplicate it. An agent has enough information to invoke route correctly and anticipate the consequences.

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 input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds meaningful interaction semantics: how 'via' selects the premise, how 'depth' affects sewer feasibility, how 'from' defaults to the nearest source, and how 'ids' default to every point of the kind. This is valuable but partly overlaps with 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 opens with 'Lay a pipe run of the plumbing project' and explains that this is the tool that creates the run, while the 'plumbing tool reads it'. The noun 'pipe run' and the verb 'lay' name a concrete resource and action, clearly distinguishing this from the sibling 'plumbing' and other edit tools.

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 clear context on how route behaves, including when 'via' is omitted, what defaults apply, and when a run is refused. It explicitly contrasts with the 'plumbing' sibling by stating that the plumbing tool reads the result, implying edit_plumbing is used to modify or create it. It does not enumerate all alternative tools, but the guidance is sufficient for the main 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?

Annotations already flag mutating/destructive behavior, and the description adds useful context: duplicate copies the active version, new starts an empty one, both switch to the new version, and edits apply to the active version. It doesn't mention irreversibility or authorization, but it discloses key side effects 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?

The description is a single dense, front-loaded sentence with no filler. Every clause conveys a distinct operation or behavioral note, and the action-parameter syntax is compact 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?

With an output schema, annotations, and full schema coverage, the description covers the critical remaining gaps: action semantics and routing to the variant list tool. The only minor ambiguity is conditional parameter requirements for each action, but the action patterns make these reasonably inferable.

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 schema has 100% coverage, but the description adds substantial semantic value by mapping each action to its parameter pattern: duplicate/new take optional names, switch/rename/delete target an index, and rename requires both i and name. It also clarifies the meaning of actions (copy vs. empty vs. switch) beyond the schema's terse 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?

The description states a specific verb and resource ('Change the plan versions (tabs)') and enumerates the exact operations: duplicate, new, switch, rename, delete. It also distinguishes itself from the sibling 'variants' tool by explicitly naming it as the list 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 gives clear routing guidance with 'The list is the variants tool', telling the agent to use the sibling for listing and this tool for changing versions. It doesn't spell out every alternative, but the operation list and resource scope make the intended context 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 already mark the tool as destructive and not read-only, and the description adds concrete behavioral details: delete removes a keyframe, clear removes the path, orbit replaces the path, and render writes a Motion-JPEG .avi file. It also documents units and visitor fallback behavior, adding value beyond the raw 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 densely packed and front-loaded with the tool's purpose, followed by a compact syntax summary. The final sentence 'The path itself is the video tool' is cryptic and could confuse rather than clarify, but overall there is little wasted text.

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 no required parameters, the description covers all actions, parameter groupings, units, and the render output format. An output schema exists, so return-value explanation is unnecessary. Examples or a note on default behavior when no action is provided would strengthen it, but no critical semantic gap remains.

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 a compact action-to-parameter language that the schema alone does not convey: add accepts cam or coordinate groups, delete takes i, orbit takes z/n, set takes fps/speed, and render takes path/w/h. It also supplies physical units (cm, degrees, m/s), which is essential semantic context.

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: 'Change the video camera path, or render it.' It then enumerates the exact operations (add, delete, clear, orbit, set, render), so an agent can clearly tell this is the video-path manipulation/rendering tool among camera and rendering siblings.

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

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

The opening line gives clear context for when to use the tool: modifying the video camera path or rendering it. It does not explicitly name alternatives or exclusions (e.g., use edit_cameras for static camera edits), but the purpose is clear enough to route an agent correctly.

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 description is unusually transparent about calculations, defaults, assumptions, and exceptions, but it also says 'wifi ... writes the standard and PoE on access points' while annotations declare `readOnlyHint: true`. Even though the final sentence routes changes to `edit_electrical`, the explicit 'writes' claim contradicts the read-only 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?

The content is dense and valuable, but it is one enormous unstructured paragraph of hundreds of words. It is front-loaded with scope, but an agent would struggle to scan the relevant action-specific details 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?

Covers outputs, defaults, norm references, exceptions, assumptions, and routing to `edit_electrical`, making it mostly complete for invoking the tool. The write/read-only contradiction and the undocumented wifi input fields keep it from being fully trustworthy.

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 schema documents `action` and `band` at 100%, and the description adds useful defaults such as `check` for action and `5` for band. However, it introduces `wifi {ids?, standard?, poe?}` inputs that are absent from the schema, which has `additionalProperties: false`, so an agent cannot tell which values are actually accepted.

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?

Clearly states it checks the electrical/telecom project against NBR 5410 and NBR 16264, with three distinct actions (`check`, `circuits`, `wifi`). It differentiates itself by explicitly routing changes to `edit_electrical`.

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?

States that `check` is the default action and explicitly routes modifications to `edit_electrical`. It does not enumerate exclusions against every sibling check tool, but the scope and the edit-tool alternative are clear enough.

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 description goes well beyond the destructiveHint annotation by explaining the actual behavior: the item becomes part of the host and moves with it, the sink/cooktop fixture is not drawn generically, and errors explain required corrections. This gives an agent a concrete model of side effects and failure-mode communication.

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 and front-loaded, covering purpose, variants, behavior, error handling, and expected reply structure in a compact paragraph. It contains a small amount of output-format redundancy since an output schema exists, but no sentence is wasted or filler.

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 tool with a rich output schema and full schema descriptions, the prose is nearly complete: it identifies hosts, item types, dimensional behavior, default z placement, and error style. Minor gaps remain only around explicit exclusions or further catalog item categories such as TV.

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 parameters in detail. The description adds a useful restatement of the item-vs-cat model and notes z defaults, but it does not substantively explain parameter meanings beyond what the schema provides. 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 states a specific verb ('Embed') and resource ('an item into joinery'), then enumerates exact application scenarios: sink/cooktop into countertop, appliance into cabinet niche, TV onto slatted panel. This level of specificity distinguishes it clearly from sibling tools like place or move, which would not imply host integration.

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 clear contextual guidance: which tool scenario applies to countertops, cabinet niches, and slatted panels, and how to supply an existing item vs a new catalog item. It does not explicitly name alternatives or say when not to use the tool, but the intended usage is strongly implied and hard to confuse.

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 description goes far beyond the readOnlyHint: it explicitly says the tool never blocks anything, leaves the drawing with the user, only reports findings, and is heuristic rather than certification. It also discloses scoring mechanics, visibility of excluded findings, fix behavior, source tiers, and how accepted findings affect scores—outstanding transparency.

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 and long, but nearly every sentence carries unique operational information essential to correct use. It is front-loaded with purpose and non-blocking behavior, though the prose could be better structured with separators or bullets given the amount of content.

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 complex review tool with seven optional parameters and heavy integration with set_home, check_layout, and accept, the description covers the full workflow: what is reviewed, what the response contains, how scores are weighted, what findings mean, how fixes prunes and acceptances work, and limits of the review. Nothing needed to invoke it 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 description coverage is 100%, so the baseline is 3, but the description adds real value by explaining that people parameters are call-local unless persisted via set_home, how scope excludes disciplines while keeping findings visible, and how city selection affects which standard applies. This supplements the schema without overexplaining parameters already well documented.

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 the tool reviews ergonomics and habitability for occupants, with a specific, well-scoped resource. It is not merely a restatement of the title, but it does not explicitly name or differentiate itself from sibling tools like check_layout, so it falls short of full distinction.

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 rich context on when parameters should be set once via set_home, how scope narrows scoring, and how fixes and acceptances interact with future reviews. It does not explicitly state 'use this instead of X', but it conveys clear usage context and references sibling workflows like set_home and check_layout.

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, so the safety profile is externally provided. The description adds useful behavioral detail about the default scope ('default every one on this storey') and output formats, but it does not disclose whether writing overwrites an existing file or other side effects. There is no contradiction with 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?

The description is compact and well-structured: it front-loads the primary action and resource, lists supported formats, then clarifies the ids parameter and the relationship to cut_list. Every sentence earns its place with no redundancy.

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 tool with only two parameters, full schema documentation, an output schema, and annotations covering destructive/read-only hints, the description provides sufficient context: file formats, default ids scope, and the companion reader tool. No critical information needed to invoke the tool 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 description coverage is 100%, so the baseline is 3. The description largely mirrors the schema for path and ids, adding only the context that ids refer to joinery builds and hand-drawn groups and that .dxf means 'boards laid out on sheets'. This is marginal added value beyond 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 uses a specific verb and resource: 'Write the cut list of joinery builds (and of groups drawn by hand) to a file'. It enumerates the exact output formats (.csv, .dxf, .svg) and differentiates from the sibling reader tool by noting 'The cut_list tool reads it.' An agent can clearly tell this tool writes cut lists rather than reading or displaying them.

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 clear context: use this tool to write cut lists to fileshare, and mentions that cut_list reads the generated output. This distinguishes the tool from its most closely related sibling, but it does not explicitly state when not to use it or how it relates to other export tools like export_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 indicate destructiveHint=true, so the description must disclose the destructive nature. It does, by stating 'Export to a file' – implying file creation/overwrite without explicit confirmation. It adds context about format-specific behaviors: `.pdf` has scale options, `.png` supports width/height, others are true scale. This goes beyond the annotations, giving the agent safety-critical details about side effects. No contradiction with annotations; the description reinforces the destructive hint by implying file system changes.

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 single, compact sentence that packs all essential information: formats, key options, and scale behavior. It is front-loaded with the primary action and quickly covers format-specific details, with no wasted words. Every clause earns its place, providing high information density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple formats, scale options) and the output schema, the description covers the main usage patterns. It does not explain return values, but the output schema exists, so that is not required. It lacks details on how the export path is used, but the schema covers that. Slight gap: it doesn't mention error conditions (e.g., missing extensions) but the format guidance mitigates that. Overall, it is complete enough for typical use.

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 parameters are fully documented in the schema, giving a baseline of 3. The description adds value by explaining format-dependent behavior: for `.pdf`, it specifies scale options and fitting; for `.png`, it mentions dimensions; and it clarifies that `.svg` is true scale. This enhances understanding beyond the schema, justifying a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Export') and clearly states the resource and key behavior: exporting to various file formats determined by the file extension. It lists the formats (`.pdf`, `.svg`, `.png`, `.glb`, `.obj`), making the purpose unmistakable. It also differentiates from siblings like 'export_cut_list' and 'render_plan' by specifying what it exports (the plan) and the output formats.

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 usage: 'Export to a file by extension' indicates the decision is based on the file extension, which is a clear contextual rule. It does not explicitly mention when not to use it or name alternatives like 'render_plan' for image rendering, but it provides enough context for an agent to infer when this tool is appropriate. The omission of explicit exclusions keeps the score below 5, but the guidance 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?

Beyond the open/read-only/destructive hints, it discloses non-obvious behavior: the report 'is kept on this machine and, while the user's telemetry is on, sent to the project', the reply is '{kept, sent}', and the agent should 'then carry on with the task'. It also warns that vague notes may get fixed in harmful ways.

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 prose is dense and uses labels rather than headings, which makes it harder to scan, but nearly every clause carries load-bearing guidance. It is appropriately sized for a 9-parameter feedback report and leads with the tool's purpose before diving into field obligations.

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 output schema and full parameter coverage, the description covers the goal, trigger, all seven required content sections, kind values, target tool, persistence/telemetry, response shape, and post-call behavior. An agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, giving a baseline of 3, but the description adds substantial meaning by defining each required section ('tried' = 'the exact call with arguments', 'expected' = what was true and how you found out) and even supplies valid values and the 'none known' escape for must_keep. This goes well beyond 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 states a specific action and object: 'Report to the developers what a tool could do better'. The list of triggers and the required sections make the tool's role unmistakable, and none of the sibling tools claim this reporting function.

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 says when to file feedback ('as it happens: a reply that answered less than was asked, a detour, a wrong conclusion...'), so an agent can recognize the right moment. It does not explicitly name sibling alternatives or say when not to use it, but no sibling offers a similar reporting channel, so that omission is minor.

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 description discloses important behavior beyond the annotations: it places a grid of fixtures, evaluates the result using the same photometry as the lighting tool, and returns placed ids plus before/after ratings. It does not mention whether existing fixtures are removed or replaced, but the additive nature of 'fill' combined with destructiveHint=false gives adequate clarity.

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-loaded: it states the action, target, fixture types, validation method, and output in two sentences. Every sentence adds meaningful information, and there is no redundant repetition of the title or 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?

Given the tool's moderate complexity, full schema coverage, and existing output schema, the description provides enough information to call the tool correctly. It explains the operation's scope, the photometry consistency, and the return content, leaving no critical ambiguity for an agent.

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 parameters. The description adds useful context about the 'lux' parameter overriding the room's reference and the work plane concept, but it does not substantially enrich parameter semantics beyond what the schema provides.

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 a specific action ('fill a room with a grid of one fixture'), the exact fixture types allowed, and the goal (reaching the room's lighting reference or a specified lux value). It also distinguishes itself from the sibling 'lighting' tool by mentioning the same photometry check, making its purpose 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?

The description implies when to use the tool: when a room needs to be automatically filled with a grid of fixtures to meet a lighting target. However, it does not explicitly state when not to use it or which alternative (e.g., 'lighting' or 'place') should be chosen for manual or partial lighting setups.

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, but the description adds critical behavior beyond that: shapes are modified in specific ways, elements continue to follow roof changes in the same undo step, and 'off' stops that behavior. This explains the persistence and undo semantics that raw annotations don't convey. No contradiction with 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 front-loaded with the core purpose and then gives examples and behavior. It is somewhat dense, with parentheticals and semicolons, but each clause adds a distinct fact. It could be trimmed slightly without losing meaning, so a 4.

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 mutation tool with an output schema present, the description covers the main effects, dynamic roof-following, undo, and off behavior. It omits prerequisites such as requiring a roof above or a note on unsupported roof types, but these are not critical given the schema and annotations. Overall adequate.

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?

Input schema has 100% field descriptions, so the baseline is 3. The description echoes 'walls, glass and panels' and adds 'joinery slatted panel' as a specific id type, but it does not add meaningful detail about 'ids', 'off', or 'above' beyond the schema. It neither elevates nor degrades parameter understanding.

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 an explicit verb and resource: 'Fit walls, glass and panels to the roof above them'. It then details concrete transformations (sloping top, split at ridge, triangle/trapezoid, slats cut), making the primary purpose unmistakable. It does not explicitly contrast with siblings like split_wall or merge_walls, but the purpose is clear without that.

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 the tool – when walls/panels should conform to a roof – but does not state exclusions or direct the agent to alternative tools for non-roof modifications. It contains no explicit 'when not' or sibling references, leaving usage guidance less explicit than it could be.

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?

Beyond the readOnlyHint annotation, the description discloses rich behavioral details: detail=summary is cheapest, ids resolve group parts, room/rect read one place, kinds/fields trim rows, parts opens groups, ndjson prints line-delimited output, and every element carries bounds and faces. It also explains id counter semantics across versions. No contradiction with 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 efficient; every clause adds practical guidance. It's a single run-on paragraph rather than structured bullets, which slightly hurts scannability, but it front-loads the most important tip ('detail=summary is cheapest') and wastes no words.

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 read-only annotation, an output schema, and 100% schema coverage, the description adds the missing semantic context: id reuse rules, bounds/faces on every piece, and how to request smaller responses. Nothing needed to call the tool correctly 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. The description adds significant meaning on top of the schema: it explains the cost model (summary is cheapest), the effect of combining filters (room/rect read one place), and how parts and ndjson alter the result shape. This goes beyond the field 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 opens with 'Home state' and uses the verb 'read' throughout, making it clear this is a read operation for home data. It is distinguishable from siblings like show_plan or open_home by the emphasis on fetching state rather than rendering or loading, but it never names an alternative explicitly.

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

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

The description implies usage: call it when you need home state, and the parameter tips ('Ask for less instead of reading everything') provide operational guidance. However, it doesn't state when to prefer this over sibling tools like show_plan or get variants, nor does it give 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?

Beyond the destructiveHint annotation, the description discloses important behavioral traits: rules 'advise, they never refuse,' only geometry-less builds fail and say why, updates keep the back anchored by default, and dry=true validates only. This adds real context beyond the annotations and contains no contradiction.

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 extremely efficient: the syntax section packs six build kinds with units and options into a compact notation, and the workshop-advice prose is a useful behavioral note, not padding. Output shape and behavior are front-loaded before the parameter grammar.

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?

All 11 top-level parameters are covered by schema or description, the p object is fully specified per kind, placement and update anchors are documented, dry mode is explained, and the return shape is explicitly stated. With an output schema present, nothing essential is missing 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 description coverage is 100%, the description carries the entire meaning of the nested p object, enumerating per-kind fields, units (cm, mm), defaults, enums like t 15|18|25 and door hinged|sliding|drawers|none, plus update/anchor semantics. This goes far beyond the structural 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 states a specific verb ('build') and resource ('joinery'), then enumerates six concrete build kinds: cabinet, slats, countertop, cove, shadow_gap, and sofa. It also specifies the returned shape ({id,name,size,parts,hardware,notes}), making it easy to distinguish from generic siblings like create or place.

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 explicit usage patterns: new builds with kind + p, placement with at or wall(+along), angle, elev, updates with id + p, and validation with dry=true. It does not explicitly name alternatives or state when not to use it, so it does not reach a 5, but the 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 already declare readOnlyHint=true and openWorldHint=falsearke; the description adds useful behavioral context by exposing the exact row schema and the concept of a selected storey that other tools depend on. There is no contradiction.

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 single dense sentence that leads with the core output format and then provides the one essential behavioral note about selection and editing. No wasted words.

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 listing tool with an output schema and read-only annotations, the description is fully sufficient: it names the fields, explains selection relevance, and points to the editing sibling.

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 has zero parameters)Skip, so there is little to explain. The description adds value by enumerating the returned columns, which is more meaningful than the empty input schema 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?

The description clearly defines the tool's output as storey rows with specific fields, and the title 'List storeys' reinforces the listing purpose. It also distinguishes this from edit_levels by noting that other tools act on the selected storey.

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 that this tool returns storey rows and that edits should go through edit_levels, naming the appropriate sibling alternative. However, it does not explicitly state conditions like 'when you need to see available storeys' or exclude non-list use cases.

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?

ReadOnlyHint is true and the description is consistent with that, adding no contradiction. It goes beyond the annotation by disclosing the computation model (inverse-square cosine law, wall shadows, interreflection/split flux) and the standard compared against (ABNT NBR ISO/CIE 8995-1), which tells an agent exactly what to expect from the result.

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 every clause carries relevant information: the physical model, the output format, the reference standard, and the sibling-tool routing. Some jargon (inverse-square cosine, split flux) may be opaque, but it is purposefully concise and not padded.

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 analysis tool with optional parameters, full schema coverage, and an output schema, the description supplies the remaining context an agent needs: what physics is simulated, what metrics are reported, what standard is referenced, and which sibling tools to use instead. Nothing essential 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%: both parameters (room id and work plane height) are already described in the input schema. The description mentions work plane and rooms but adds no new semantic meaning or usage details beyond what the schema provides, 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 description clearly identifies this as a lighting evaluation/rating tool: it computes photometric metrics per room and replies with a structured verdict against a reference standard. It distinguishes itself from siblings by describing what fill_lighting does (places fixtures) and where to set a piece's light (place/update light), so an agent can tell them apart.

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 routes the agent away from this tool when the goal is placing fixtures ('fill_lighting places the fixtures a room needs') or setting a single piece's light ('Set a piece's light with place/update light'). It does not explicitly say 'use this when you need to rate lighting,' but the title and output description make that context 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 already declare readOnlyHint=true and openWorldHint=false, covering the safety and world-model aspects. The description adds the structure of the returned data (wall types vs finish patterns), providing some value beyond annotations. It does not describe pagination, filtering, or any side effects, but for a simple list tool this is minor.

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 concise, a single sentence with no filler. The bracket notation is compact, but the unexplained 't' in '[id,name,t]' and the ambiguous 'tile' in finish patterns reduce clarity slightly. Still, every word 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?

For a parameterless, read-only list tool with an output schema present, the description is sufficient. It identifies the two main categories an agent would receive. The cryptic tuple field names are not ideal but are recoverable from the output schema, so the completeness gap is small.

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 has zero parameters, so there is no parameter semantics to explain. The baseline for 0-param tools is 4, and the description correctly avoids inventing parameter guidance. The schema coverage is trivially 100% because the schema is empty.

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 (wall types and finish patterns) and the content of the listing. The title reinforces the list action. It does not explicitly differentiate from siblings like 'catalog', but the material-specific context makes it clear enough.

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 tool's purpose implies when to use it (when wall types or finish patterns are needed), but there is no explicit guidance about alternatives or when not to use it. Given the parameterless, query-like nature of the tool, the lack of exclusions is acceptable but still leaves the agent inferring usage from context.

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 mark the tool read-only; the description adds useful behavioral detail about result shapes ({clear}, {spans}, {fit}), what counts as free floor, and the default z height band. It does not contradict the annotations and goes beyond what they convey.

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 and telegraphic, yet every clause carries information about a mode or result. The single-paragraph structure and compact pseudo-JSON examples reduce scannability, but there is no filler and the core purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, multi-mode measurement tool with an output schema, the description covers the main invocation intents and their result semantics well enough for correct use. It is slightly less complete on error/edge cases like combining mutually exclusive modes, but the schema and optional parameters mitigate that.

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 combination semantics: dirs picks sides, gap+grow produces a fit answer, axis+at returns spans, and z bounds the analyzed height band. It does not mention the range parameter, but the schema fully documents 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 opening 'Tape measure over the plan, in cm' plus the enumerated modes (from-alone free floor, from+to distance, axis+at probe spans, gap+grow fit) makes the tool's purpose concrete and distinguishable from sibling design/editing tools. It does not explicitly name a sibling it is not, 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?

The description gives explicit mode-selection conditions: 'from=<id> alone', 'from+to', 'axis+at', and 'Add gap and grow', which tells an agent which parameter combination is appropriate for which measurement intent. It does not name alternatives or state when not to use the tool, so it misses the top of the scale.

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

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

With destructiveHint=true already indicating destructive behavior, the description goes further: the longest wall keeps its id and build, the others are deleted, doors and windows stay, gaps close, and the reply names the remaining id. This adds substantial behavioral context beyond the annotation and accurately aligns with the destructive hint.

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 main purpose and then covers side effects efficiently. The last sentence ('Straight walls on one storey whose centerlines run inside one another; the reply names the id that remains.') is slightly clunky and could be integrated into the main clause, but every sentence contributes meaningful 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?

For a destructive, single-parameter tool, the description covers the operation, side effects on walls and openings, gap behavior, and output essence. Since an output schema exists (per context), the description need not detail the return structure. It is complete enough for correct invocation, though it could briefly mention error cases (e.g., non-collinear 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 schema description for 'ids' already states 'in order along the line they make,' giving 100% coverage. The tool description reiterates the order implicitly but adds no new parameter-specific semantics beyond the schema. Baseline 3 is appropriate here.

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 ('Join walls that run along the same line into a single wall') and immediately gives concrete scenarios (partition interruption, imported segments, drawn twice) that distinguish it from related tools like split_wall and delete. This is not a tautology; it tells an agent exactly what the tool accomplishes.

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 provides clear contexts for use ('the wall a partition interrupted, a stretch imported as many segments...') and imposes a condition ('Straight walls on one storey whose centerlines run inside one another'). However, it does not explicitly mention the alternative split_wall or state when merging should not be used, so it falls short of fully explicit when/when-not guidance.

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