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

Annotations already cover read-only/idempotent, so the description correctly spends its words on non-obvious behavior: procedural reports use the fixed build frame while saved vehicles use body-local frames, and the largest body is the default rather than necessarily the hull. It does not discuss report shape or station defaults in prose, but an output schema exists.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the measurement purpose before any caveats, and every sentence carries a distinct constraint (footprint vs material, source frames, body_id, seal-test exclusion). The middle sentence is dense and stacks two frame cases, costing a little readability.

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 the complexity of a 9-parameter, any-of-source analysis tool: which source to pick, which frame applies, and which sibling handles sealing. With an output schema present it needn't describe results, so the remaining gap is minor.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above baseline by explaining the semantic consequence of body_id (pick it when the largest body is not the hull) and the frame difference between the name/spec/preset sources, which the schema does not state.

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

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

States a specific verb (measure) and precise resource (hull material, floor gaps, partial-face seams at z stations, split into keel/walking floor/rim), and explicitly frames it against the misconception that footprint equals solid material. Distinguishable from siblings like preview_hull and check_seal without opening any schema.

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

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

Gives explicit when-to-use (before saving to check depth and floor height, or to study a saved hull) and names the alternative for a different job: 'not a seal test (use check_seal)'. Also flags the body_id decision case for multi-body vehicles.

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 cover read-only/idempotent/closed-world, and the description adds genuinely new behavioral context: results are paged one section per call, axle span reflects mounting origins rather than tyre-centre track, and multi-body vehicles stay separate. Those interpretation caveats are exactly what prevents an agent from misreading output. The trailing 'Read-only' merely echoes the annotation but is harmless rather than contradictory.

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?

Four dense sentences with no filler, and the core purpose plus section/paging model are front-loaded. The paragraph is somewhat run-on and packs caveats into the same block, but every clause carries information.

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

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

For a 10-parameter, read-only analysis tool with an output schema and full annotation coverage, the description supplies purpose, alternatives, paging model and known limitations. Parameter-level defaults and return shape are correctly left to the schema/output schema, so remaining gaps are minor.

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 a behavioral rule not obvious from the schema: one section per call with paging, which clarifies how section, limit and offset interact. It stops short of explaining wheel_roles/exclude_wheel_ids or the forward-vector semantics, leaving that to the schema.

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

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

Specific verb (measure) plus resource (saved land vehicle or land draft) and an enumeration of what gets measured: body-local axles, wheelbase, mounts, light axes, controls, equipment. It also explicitly differentiates itself from the sibling analyze_vehicle by scope ('general part audits of boats use analyze_vehicle'), so an agent can route without opening either schema.

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

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

Gives concrete entry points ('references from find_land_vehicles or your own draft before editing') and names the alternative tool plus the condition that selects it (boat/part audits → analyze_vehicle). It also states where the tool stops being sufficient ('suspension, steering sweep and mesh fit still need game checks'), which is a real when-not caveat.

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 cover the read-only/idempotent/non-destructive safety profile, yet the description still adds real behavior: results arrive one section per call with paging, multi-body vehicles are handled, and findings are explicitly observations rather than game state verification. That last caveat is a non-obvious trust signal an agent would otherwise get wrong.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and scope are front-loaded in the first clause, with routing rules and caveats after. Slightly dense — the enumerated section list partially duplicates the schema's section enum — but every sentence still carries information.

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

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

With six parameters, an output schema present, and rich annotations, the remaining burden is purpose, routing, and trust caveats — all covered. An agent can decide to call it, pick a section, and page through results without further info.

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 name/limit/offset/search/source/section are already fully documented, which sets the baseline at 3. The description's list of reportable areas mirrors the section parameter and adds the 'one section per call' framing, but nothing beyond that (no guidance on section ordering or search interaction).

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

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

States a specific verb and resource ("Audit how a saved vehicle is built") and then enumerates exactly what it reports: parts, logic links, controllers, bodies, placement issues, connection candidates, open transmission ports. It explicitly distinguishes itself from two siblings by name, so an agent can separate it from analyze_land_vehicle and analyze_hull without opening a schema.

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

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

Gives both selection conditions ("learn from the player's vehicles or to debug a save") and explicit routing rules to alternatives (wheel layouts → analyze_land_vehicle; hull material and floor gaps → analyze_hull). When-to-use, when-not-to-use, and the alternative are all present.

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 destructive=true and non-idempotent, and the description adds the crucial detail that existing drivers of the target inputs are replaced atomically, plus that commit=true creates a single undo step and stale revisions are rejected. That is genuine value beyond the annotations, though the return-behaviour sentences largely restate schema parameter descriptions rather than adding new behaviour.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the edit_connections contrast are front-loaded, but the middle collapses into a run-on chain of build rules and flag semantics that mirror the schema, and the trailing 'Tune behaviour in game' earns little. It could be split into short usage and returns lines without losing 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?

With annotations, an output schema and fully described parameters carrying the structured load, the description supplies what's missing: assembly preconditions, replacement atomicity, and the preview/commit workflow. An agent has enough to call it correctly; only explicit failure modes (beyond stale revisions) are 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?

With 100% schema description coverage the baseline is 3, but the description adds real semantics: the engine field accepts one id or a list (twins share throttle gate and starter) and the clutch gate must be distinct from the idle throttle gate. These are cross-parameter constraints the schema cannot express.

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?

Opens with a specific verb and resource ('Configure and wire a reusable control set-up') and enumerates exactly which sub-assemblies are covered. It also explicitly contrasts itself with the sibling edit_connections, so an agent can pick between them without opening either schema.

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

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

States the alternative ('instead of wiring each link with edit_connections') and the precondition (explicit current part ids from query_connections). It also gives per-assembly constraints — clutch needs its own gate, starter is manual/hold, reverse must be selected while stopped — which steers correct invocation.

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 cover the safety profile (readOnly, non-destructive, idempotent), and the description adds genuinely new context: the possible 'indeterminate' outcome, that unsupported sealing geometry degrades confidence, and that an annotated image plus a compartment report is produced. It does not discuss cost, limits, or what 'seeds' fallback behavior means when omitted, which keeps it below the top mark.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and mechanism come first, followed by usage timing, caveats, and return shape, in four tight sentences with no filler. Every sentence carries distinct information.

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

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

With no output schema, the description correctly discloses the return value (image with highlighted escape path and a connected-compartment report). For a three-parameter read-only check, purpose, trigger, caveat, and output are all present.

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 design, seeds and door_state are already fully documented in the schema, including the enum-like closed/open values and the imported-vs-generated seeds rule. The description adds nothing parameter-specific beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource — testing whether a draft is watertight — and describes the mechanism (tracing from interior points to the outside) plus the tri-state result per compartment. This is clearly distinguishable from nearby siblings like analyze_hull or preview_hull, which imply different operations.

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

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

'Use it after edits that touch the hull or doors' gives a clear triggering condition, and the note about unsupported sealing geometry warns when a confident pass is impossible. It stops short of naming an alternative tool to use instead when geometry is unsupported, so it is not a full when/when-not/alternative statement.

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, it discloses important behavior: it writes only a stored draft and never a game file, refuses an existing name, and returns a preview image, notes, and revision. These details materially clarify side effects and constraints for a non-destructive but non-idempotent write tool.

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 action and return values, then gives workflow and preset details. It is somewhat dense, especially the semicolon-separated preset summaries, but there is little true waste for a tool with downstream workflow dependencies.

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 creation tool with no output schema, the description supplies the missing return behavior, the draft-only safety boundary, the name constraint, and the full follow-up workflow through validation and saving.

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 useful semantics for spec.preset by naming the default utility_buggy and summarizing the contents of humvee_4x4 and utility_4x4. It repeats the existing-name constraint already present in the schema but adds meaningful preset 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 uses a specific verb and resource: 'Create a new land vehicle draft'. It also clarifies the return values and distinguishes the draft from a real game file, so the agent can tell what this tool does and what it does not do.

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

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

It gives an explicit workflow: read land_vehicle_guide first, then complete with query_parts/edit_parts and connection tools, check with preflight_vehicle, and save with save_vehicle. It also states the prerequisite that the design name must not already exist.

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 readOnly/idempotent/non-destructive, so the description's "Read-only" is restatement. The value-add is real though: it discloses the return shape ("a text table") and, importantly, the unit semantics — spec units, real-world metres only when the spec carries a `scale`. That is non-obvious behavior an agent would otherwise get wrong.

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?

Four sentences, front-loaded with what is tabulated before the use case and the units caveat. The parenthetical about scale is worth its space; a couple of clauses could be tightened, but there is no 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?

With an output schema, rich annotations, and full parameter documentation, the description only needs to supply intent, units, and usage — all present. It is complete enough to invoke correctly; only the lack of sibling routing keeps it short of 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 description coverage is 100%, so the baseline is 3. The description reinforces the station/transom semantics of `step` and explains the `y` default that `spec`/`patch` can control, but it adds no format or precedence detail beyond what the schema already documents for spec, patch, design, preset and spec_path.

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

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

States a specific verb and resource ("Tabulate the deck at stations from the transom") and enumerates the three quantities returned: deck height above keel, the default `y` for a superstructure box, and deck half-beam. That is far more specific than the name alone. It does not, however, contrast itself with near neighbours like preview_hull or analyze_hull, so an agent still has to infer the boundary.

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

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

"Use it to place turrets and deckhouses on a sheered deck instead of guessing heights" gives a concrete positive use case and implies the alternative (estimating). There is no explicit when-not or named sibling to prefer in other situations, which keeps it out of 5 territory.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is mostly covered. The description adds genuinely useful context — original XML and settings stay lossless, stale revisions are rejected, and commit=true collapses the batch into one undo step — but it doesn't discuss failure modes for a partially invalid batch or rate/size limits beyond the schema's maxItems.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and sibling routing in the first two sentences, then constraints, then return/commit behavior. Slightly dense and the operation shape listing duplicates the discriminated union in the schema, costing a little efficiency.

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

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

With no output schema, the description carries the return contract and does so ('returns the wires added and removed, warnings and the new revision; preview=true adds the image and full notes'). For a destructive 5-parameter mutation, only batch failure/rollback semantics are left implicit.

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 commit/preview/design/revision/operations are all documented in the schema and the description largely restates the op shapes. It does add real meaning the schema cannot express — signal outputs connect to inputs, electricity is bidirectional, one driver per signal input — which is why this sits above a pure restatement.

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

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

States a specific verb and resource ('Add or remove typed control and electrical wires in a draft') and immediately scopes it against siblings, noting that pipes/shafts go to route_connections and whole assemblies to apply_vehicle_assembly. An agent can pick this over route_connections without opening either schema.

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

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

Explicit routing: pipes and shafts use route_connections, whole starter/clutch/brake/light set-ups use apply_vehicle_assembly. It also names the prerequisite ('Uses the query_connections revision') and states the domain rules for what may connect.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real context on top: atomic batch ordering, stale revisions rejected, preview=true returns image plus full notes, commit=true yields exactly one undo step (undo_edits), and what the response contains including newly assigned ids like edit:0:0.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and one atomic-batch framing, and nearly every clause carries information an agent needs for a 10-variant operation union. The middle section is a dense run-on paragraph, so some op semantics are harder to scan than they could be, but little is 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 complex, highly-branching mutation tool with no output schema, the description covers the operation list, required inputs per op, return contents, and preview/commit behavior. Minor gaps remain: the units/format of bounds, whether an empty selection means 'all parts', and how multiple ops interact within a batch beyond ordering.

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 3 would be the baseline, but the description goes well beyond the schema, which has almost no per-property prose: it explains delta in blocks, that repeat's count is *additional* copies, that rotate takes a local-to-world matrix or 'r' string plus pivot, mirror's axis/plane, mirror bitmask values (1=x, 2=y, 4=z), selection shapes for selection ops, and the max_force_scale=1 default for prebuilt engines.

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?

Opens with a specific verb set and resource plus scope: 'Add, remove, move, rotate, paint or copy parts in a draft as one atomic batch.' It also explicitly routes non-part edits away ('Wires and pipes use edit_connections and route_connections'), so an agent can distinguish it from the connection-editing siblings without opening a schema.

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

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

States the prerequisite 'Pass the revision from query_parts' and names the alternative tools for wires/pipes, plus commit/undo semantics. It does not spell out when a repair/validation workflow should be preferred over direct part editing, but the operating 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, idempotentHint, and destructiveHint=false, so the trailing 'Read-only' adds nothing. What does add value is the disclosure of matching semantics: only body components are counted (not controller internals), and wheeled boats or aircraft can match, so results carry false positives. That is genuine behavioral context beyond structured fields, though return shape and paging behavior are left to the output schema.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first clause and every sentence carries signal: scope, counting rule, false-positive caveat, follow-up routing. It is dense and clause-stacked in places ('including unnamed experiments, with paging'), and the final 'Read-only.' is redundant with annotations, but nothing is wasted overall.

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

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

With an output schema present, return values need no explanation, and the description covers everything else an agent needs: what corpus is scanned, what counts as a match, the false-positive caveat, paging, and the correct next tool. No ambiguity remains about how to call or interpret it.

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

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

Schema description coverage is 100% with clear per-parameter text for kind, limit, offset, search, and source, so the schema carries the load and baseline 3 applies. The description only loosely maps to parameters — 'wheel or track layouts' gestures at kind, 'installed Workshop items' at source, and 'including unnamed experiments' hints that search may not reach unnamed vehicles — but it adds no format or edge-case detail 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?

States a specific verb and resource — scanning the player's saved vehicles or installed Workshop items for wheel/track layouts as land-build references — and scopes it (unnamed experiments included, paged). It explicitly distinguishes itself from list_game_vehicles (names only) and names analyze_land_vehicle as the deeper follow-up, so an agent can place it in the sibling set without opening a schema.

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

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

Gives the routing rule directly: use analyze_land_vehicle to follow up on a hit, and use list_game_vehicles if only names are needed. It also sets expectations about when a result is *not* conclusive — 'a hit says nothing about a vehicle's purpose or quality' — which prevents over-reading matches.

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 read-only, idempotent, non-destructive, but the description adds real operational context beyond them: it explicitly states it runs no test, explains that stale reports arise when the definition or test vehicle changed, and discloses the empty-result behavior ('returns no checks when nothing was recorded').

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 scope statement is front-loaded and the follow-up sentences are short and purposeful, covering usage timing and empty-result behavior. The first sentence is dense with a parenthetical definition, but nothing is wasted.

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

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

Given a single well-documented parameter, an output schema, and full annotation coverage, the description supplies everything an agent needs: what evidence is returned, when to consult it, that no tests execute, and what an empty response means.

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

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

With a single parameter at 100% schema coverage, the schema already carries the meaning ('Definition id the player tested, e.g. "rudder"'). The description's 'for one part' reinforces the scope but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

The description names a specific verb and resource — 'Read the player's recorded in-game checks for one part' — and enumerates exactly what is returned (latest result per test case, stale counts, contradictory checks). This clearly separates it from sibling read tools like get_part_definition or get_part_orientation, and the line 'runs no test' distinguishes it from validation 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 an explicit trigger: 'Use it before relying on an orientation or mounting rule for that part.' That is clear situational guidance, though it does not name a specific alternative tool for when the caller wants to actually re-run or apply checks.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the result is 'fully resolved' and suitable as a starting spec to copy and change. It does repeat 'Read-only,' but does not contradict 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?

Two tight sentences, front-loaded with the core behavior, then the use case and a pointer to the guide. No sentence is wasted.

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

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

For a single-parameter read tool with full schema coverage, rich annotations, and an output schema, the description provides everything needed: purpose, usage modes, a copy-use case, and a pointer to hull_design_guide for field explanations.

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 single preset parameter already documents that the name comes from list_hull_presets and should be omitted for defaults. The description restates the preset/default distinction but adds no format or syntax details 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?

States a specific verb and resource: 'Return the fully resolved hull spec, every parameter with its value.' It also clarifies the two modes, a preset or the defaults, so an agent can distinguish it from list_hull_presets or hull_design_guide.

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

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

Gives clear usage guidance: use it to see what a preset sets or as a starting spec to copy and change. It also names hull_design_guide(topic="spec") as the alternative for understanding fields. It lacks explicit exclusions, but the context is strong.

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

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

The annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds the important failure mode ('fails when the definition is not installed') and notes that placement permission is returned with a reason when denied. It does not touch on cost or limits, but it meaningfully extends the structured metadata rather than repeating it.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the return contents, then usage ordering, then the failure condition. The field enumeration is dense but each item is decision-relevant for an agent checking part compatibility; nothing is redundant padding.

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

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

For a one-parameter read-only lookup with an output schema (so return shape needn't be spelled out), the description covers purpose, sequencing, alternative tool, and error behavior. Nothing an agent needs in order to call 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% and the single 'definition' parameter already documents the id format and points to search_parts. The description only reinforces the search_parts discovery path and adds no new syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Return one installed part's definition') and then enumerates exactly what the payload contains: footprint voxels, attachment/sealing surfaces, logic nodes, settings, mass, seal coverage, placement permission. It also names the sibling (get_part_orientation) that handles rotation, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit sequencing ('Use it after search_parts') plus the concrete questions it answers (how a part mounts, connects or seals), and routes the rotation question to get_part_orientation. That is a clear when-to-use plus a named alternative with the condition that selects it.

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

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

Annotations already establish read-only/idempotent/non-destructive, and the description adds real value beyond them: it discloses that 'right placements can require mirror' and that the returned arrow signs 'still need checking in game' — an honest limitation an agent would otherwise not know. It also states the output contract (effective rotation plus proper r and mirror).

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and outcome are front-loaded in the first sentence, followed by compact examples and a caveat. It is dense with domain terms but nearly every clause carries usable information; the road-wheel sentence is the only one that could be tightened.

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

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

With an output schema and full annotation coverage, the description only needs to supply intent, examples and limits — which it does, including the in-game verification caveat and downstream consumers. What it omits (return structure, unit-vector constraints) is already covered by structured fields.

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 does add non-trivial meaning: it explains that targets are a per-local-axis world-direction map and identifies which axis keys matter for different part families, plus the mirror caveat for mirrored placements. It stops short of format details (integer unit vectors are only stated in 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 first sentence names a specific verb and resource ('Explain a part's local mounting, motion and function axes') and states the computational outcome ('solve the rotation that points them in the requested world directions'). It also positions the result relative to a sibling ('proper r and mirror for edit_parts or XML'), so an agent can tell this apart from edit_parts itself.

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

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

The description gives concrete usage context via worked examples for two part classes (Fin Rudder needs mount_normal/span_axis; road wheels need axle_axis, wheel_reference_up, wheel_forward). It implies this is a pre-edit analysis step but never explicitly says when NOT to use it or names an alternative for a different need.

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/idempotent/destructive status, so the bar is lower. The description still adds value beyond them: it enumerates what the report contains and notes "with notes on anything missing," telling the agent the output is a diagnostic that flags absent resources rather than a bare path dump. "Never creates folders" is a useful reassurance even if it partly restates readOnlyHint.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what is reported, followed by when to use it and a safety note. The final "Read-only; it never creates folders" clause is partially redundant with the annotations, which is the only wasted space.

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?

Zero parameters, full annotation coverage, and an output schema mean the description only needs to cover purpose and trigger conditions, and it does both. Nothing an agent needs in order to call this correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies the call is argument-free by describing a full server-side report.

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

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

States a specific verb (report) and enumerates the exact resource set: server version, Stormworks vehicles folder, part definitions, stored designs, build cache, and tool timeout. No sibling tool in the list does anything comparable, so the agent can tell immediately that this is the environment/path diagnostics 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?

"Use it when a tool cannot find the game, its parts or the player's vehicles" gives an explicit trigger condition for invocation, which is exactly the failure mode an agent would be confused about. It stops short of naming alternatives or stating when not to call it, but the trigger is concrete enough to route 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?

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real context beyond them: it discloses the failure mode for an unknown run id and explains the meaning of export_matches and draft_matches (whether the exported file and draft are still the ones tested), which the annotations do not 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?

Three short clauses, front-loaded with the operation and then the payload, with no filler. Every sentence earns its place by adding either return content or failure behavior.

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

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

For a one-parameter read tool with full annotations, a complete input schema, and an output schema, nothing needed to call it correctly is missing. The description goes further by explaining the two match fields, which aids interpretation of the result.

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 is a single parameter with 100% schema description coverage, and the schema already states it is a '24-character run id returned by prepare_vehicle_validation.' The description adds no format or provenance detail beyond that, so the baseline 3 for high schema coverage applies.

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

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

The description opens with a specific verb+resource ('Read a validation run') and then enumerates exactly what the reading yields: the checklist with recorded results and evidence, plus export_matches and draft_matches. That content list distinguishes it implicitly but clearly from prepare_vehicle_validation (creates the run) and record_vehicle_validation (records results).

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

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

Usage is implied rather than stated: you read a run that already exists, and the 'fails when the run id is unknown' note signals a precondition. No alternative tool is named and there is no explicit when/when-not guidance relative to prepare_vehicle_validation or record_vehicle_validation, leaving the agent to infer the workflow position.

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

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

The annotations already establish read-only, idempotent, non-destructive, non-open-world behavior, and the description reinforces read-only while adding that the return is Markdown. It also explains the efficiency behavior of fetching focused topics rather than repeatedly retrieving the full guide. The remaining behavioral gaps are minor because the safety profile is already covered by annotations and the return shape is covered by an output schema.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with what is returned, then usage guidance, then the sibling alternative. Every sentence contributes practical routing or invocation information with no 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 single-parameter documentation retrieval tool with an output schema, the description provides what it returns, the recommended topic strategy, and the relevant alternative tool. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the enum values are already well documented. The description still adds procedural meaning by identifying workflow as the starting topic and focused topics as the preferred alternative to full, which helps an agent choose parameter values in 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 uses a specific verb and resource: return the boat design guide as Markdown. It explicitly distinguishes this guide from the separate road/land vehicle guide by naming land_vehicle_guide, so an agent can route correctly without inspecting schemas.

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

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

It gives explicit sequencing guidance: read topic="workflow" before designing a boat, then fetch focused topics as needed instead of resending the full guide. It also names the alternative for road and land vehicles, leaving little ambiguity about when to use this tool versus land_vehicle_guide.

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

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

Annotations only flag non-read-only, non-destructive, non-idempotent. The description goes well beyond: source is never mutated, configured/wired parts are protected, three specific failure modes (draft name exists, multi-body, older data version), and that it returns the part count. That is rich behavioral context an agent could not infer from 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 core action and the source-unchanged guarantee are front-loaded, followed by workflow, constraints, and return value. Dense but every clause carries information; nothing repeats the schema or annotations.

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

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

Output schema exists and the description still states the return ('part count'). Combined with the failure conditions and workflow, an agent has everything needed to call this correctly and interpret the result.

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 name, design, and source are already fully documented, including the Workshop ID alternative and the list_designs cross-reference. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Copy an existing single-body vehicle (data version 3) into a new editable draft') plus the key invariant that the source file is never changed. This cleanly separates it from sibling tools like create_land_vehicle or save_vehicle.

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

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

Explicitly names the use case ('modify a vehicle the player already has') and lays out the follow-on workflow (query_parts/edit_parts, preview_vehicle, save_vehicle under a different name). It also enumerates failure conditions, which tells the agent when not to bother calling it.

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

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

Annotations already cover the safety profile, and the description's closing 'Read-only' merely restates them. It does add real behavioral detail beyond annotations: what is returned (image plus caption), that highlight yields box position in spec units and game-metre heights above the keel, and that pitch 0 or ±90 triggers metre rulers with defined axes.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and its differentiator before the return-value and ruler details. Dense but mostly earns its space; the parenthetical axis definitions and the redundant 'Read-only' tail are the only mild padding.

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

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

With 14 optional parameters and no output schema, the description usefully documents the return shape (image plus caption, plus highlight coordinates) and one important rendering behavior. Gaps remain around failure modes and how source/workshop interplay with name, though the schema covers those fields well.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by tying specific parameter values to observable output — the ruler behavior at pitch 0/±90 and the extra positional reporting when highlight is set. These are cross-parameter consequences the per-field schema text does not state.

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

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

States a specific verb and resource — render one large view of a hull design or saved vehicle — with the framing 'like a camera you can point' that distinguishes it from fixed-angle preview tools. The contrast with 'the fixed previews' makes the scope unambiguous against siblings like preview_hull and preview_interior.

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

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

Explicitly routes the agent: use this to inspect details the fixed previews hide, and use preview_hull for the standard set of views. That names the alternative and the condition that selects it, leaving little to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the output is Markdown and lists the guide's topics, but it does not add much behavioral context beyond what annotations and the output schema already 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 compact and front-loaded: it states the return type and contents first, then gives usage guidance and the sibling alternative. Every clause adds useful 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 zero-parameter guide tool with an output schema and read-only annotations, the description provides everything an agent needs: what it returns, what it contains, when to read it, and which alternative to use for boats.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline for zero-parameter tools is 4, and the description appropriately does not invent 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?

States a specific verb and resource: 'Return the road and land vehicle guide as Markdown,' then enumerates the guide's contents. It clearly distinguishes itself from sibling tools by naming create_land_vehicle and hull_design_guide.

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

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

Explicitly says to read it before create_land_vehicle or 'any land work,' and directs boat-related work to hull_design_guide instead. Both the when-to-use condition and the alternative are stated directly.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful scope details: it lists only drafts stored on this server, includes specific draft categories, and excludes game-folder vehicles. It does not describe return structure, but an output schema exists.

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 primary action and scope, then adds routing guidance and the alternative tool. The parenthetical tool references are dense but each earns its place by clarifying draft categories.

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, rich annotations, and an output schema, the description supplies everything an agent needs: what is listed, how names are used, and which sibling tool handles game-folder vehicles.

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 the baseline is 4. The description mentions `design` as a name to pass to other tools, which gives useful downstream context but is not a parameter of this tool.

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

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

The description gives a specific verb and resource: list the names of drafts stored on the server. It also distinguishes the categories of drafts and explicitly separates server drafts from vehicles in the game's folder, which is handled by list_game_vehicles.

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

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

It explains how to use the returned names: pass a name as `design` to other tools or to load_design to read it. It also names the alternative tool for game-folder vehicles, so the agent knows when not to use this 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/idempotentHint/non-destructive, so the safety profile is covered. The description still adds value beyond that by disclosing a failure mode and its remedy — "fails when the folder is missing (set SW_VEHICLES_DIR)" — plus that results are sorted. It doesn't say what an empty folder or a folder with non-vehicle files yields, so not a full 5.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action, then routing, then the failure caveat. No filler; each sentence carries distinct 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?

Single optional parameter, full schema coverage, output schema present (so return shape needn't be explained), and read-only annotations. The description covers the one non-obvious operational fact — the required SW_VEHICLES_DIR — and nothing material 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?

Schema coverage is 100% and the 'search' parameter is fully documented in-schema (case-insensitive substring; empty = all). The description does not restate or extend the search semantics — "Pass a name to ..." describes downstream flow, not the filter — so baseline 3 is correct.

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

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

Specific verb + resource + scope: "List the vehicle names in the player's Stormworks vehicles folder, sorted." It also distinguishes itself from list_designs ("Drafts stored on this server are listed by list_designs"), so an agent can tell the two list tools apart immediately.

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?

Explicit downstream routing: "Pass a name to preview_game_vehicle, inspect_view, analyze_vehicle or import_vehicle." It also carves out the boundary against the sibling list_designs, giving both when-to-use and when-not-to-use in two sentences.

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 cover readOnly/idempotent/destructive/closed-world, and the description confirms 'Read-only' while adding the useful trait that these are built-in (i.e., a fixed, non-user-mutable set) rather than user-authored designs. It stops short of anything like ordering, count, or pagination, but with annotations this rich and an output schema present, that is a modest gap.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource and its contents, then downstream usage, then sibling disambiguation — a sensible priority order. The trailing 'Read-only.' repeats the annotation and is the one sentence that doesn't fully earn 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, annotated, output-schema-backed catalog tool, nothing an agent needs to call it correctly or act on the result is missing: it knows what comes back, that it is a fixed built-in set, and what to feed the names into next.

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?

Zero parameters, so baseline is 4. The description usefully defines what a preset name *is* in this system by describing how it is consumed downstream by preview_hull, save_hull and get_hull_spec.

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

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

States a specific verb+resource ('List the built-in boat hull presets') and enumerates exactly what each entry contains (name, one-line description, dimensions, interior flag). It also explicitly names the two nearest lookalikes, list_designs and list_game_vehicles, so an agent can separate the preset catalog from stored or saved vehicles without opening a schema.

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

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

Tells the agent what to do with the output: pass a returned name as `preset` to preview_hull or save_hull, or to get_hull_spec for the full value set. Alternatives are routed explicitly (list_designs for stored designs, list_game_vehicles for the player's saved vehicles), which is a complete when/when-not map for a catalog 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description reinforces 'Read-only' and adds a useful caveat that geometry is not preset-specific, but otherwise spends its behavioral budget on workflow rather than deeper characteristics like response shape or pagination.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with what the tool returns, then the follow-up workflow, then the geometry caveat. 'Read-only' slightly duplicates the annotations, but the rest 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 supplies everything an agent needs: contents of the listing, the downstream steps involving edit_parts and apply_vehicle_assembly, and the geometry caveat. Return-value details are appropriately left to the output schema.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate on the input side, and it correctly does not invent 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?

States a specific verb and resource ('List the reusable control assemblies') and enumerates exactly what the result contains: part ids each assembly must be bound to and expected logic gates. This is clearly distinguishable from apply_vehicle_assembly and edit_parts, which are the write-side 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?

Gives a concrete workflow: place required gates with edit_parts, then bind the queried ids with apply_vehicle_assembly. That tells the agent where this tool sits in the sequence and which siblings follow it, though it does not state explicit when-not-to-use conditions.

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

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

The annotations already establish that this is a safe, idempotent, read-only lookup. The description adds useful non-safety behavior: it returns size keywords with metre equivalents and edit areas that are at least that large, and it explains how the result feeds later preview summaries. 'Read-only' is redundant, but the added context is substantive.

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 list contents and then the downstream workflow. It is reasonably compact, though the trailing 'Read-only' repeats the annotations and the workflow sentence could be slightly tighter.

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 annotations and an output schema, this description covers what is returned, how the result is used, and the safety profile. Nothing needed to call 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?

The tool takes zero parameters, so the baseline is 4. The description appropriately adds no parameter detail because there are none to explain.

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 verb and resource: it lists workbench size keywords and the edit areas that fit each size. It is functionally unambiguous, but it does not explicitly differentiate itself from any sibling tool by name.

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 a concrete workflow: ask the player which bench they will build at, then set that value as `bench` in the spec so preview summaries can report fit. It does not mention alternatives or exclusions, but the intended use 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 readOnly/idempotent/non-destructive, so the safety bar is low, but the description still discloses what actually differs per call: a hull draft returns a full spec while an imported/land draft returns kind, source, current revision, coordinate frame and edit log. The named failure mode adds further context. Minor gap: it does not mention size or cost characteristics of loading a large hull spec.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by routing, payload shape and failure mode in a tight sequence with no filler. The routing sentence is densely packed (two tools and a patch syntax in one clause) but still parses cleanly.

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

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

An output schema exists, so return values need not be enumerated, yet the description still tells the agent that the payload shape branches by draft kind and which editing tools to use instead. Given one required parameter, rich annotations and a closed-world read, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the single parameter is already documented as coming from list_designs. The description only adds the constraint that an unknown name fails, which is useful but is behavioural rather than additional syntax or format detail, so the high-coverage baseline of 3 applies.

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

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

Opens with a specific verb+resource ("Read a stored draft") and immediately delineates two result shapes by draft kind (hull spec vs. imported/land metadata). It names the siblings that handle the mutation path, so an agent can separate it from preview_hull, store_design, query_parts and edit_parts without opening a schema.

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

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

Gives explicit routing: to change a hull draft use preview_hull/store_design with design=name and patch, and for imported/land drafts use query_parts/edit_parts rather than a spec. It also states the failure precondition (no draft with that name), which is exactly the when-not guidance an agent needs.

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 declare a non-read-only, idempotent, non-destructive write; the description explains exactly what that write is ('one temporary HTML page, replaced on each call, and changes nothing else'), which confirms and sharpens the annotation profile. It additionally discloses rendering behavior an agent could not otherwise know: installed component meshes with explicit fallbacks, and that articulated vehicles render only the largest body unless body_id is set.

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?

Four short sentences, each carrying distinct information: what it does, why the agent must delegate viewing, the exact write side effect, and the rendering/articulation caveat. Nothing is repeated from the schema or wasted.

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

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

For a 9-parameter tool with full schema coverage, an output schema, and supporting annotations, the description supplies the remaining context an agent needs: the invisible-to-caller nature of the viewer, the precise mutation footprint, and the articulation/mesh defaults. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the articulation default ('largest body alone unless body_id is given') and the mesh/fallback sourcing. It doesn't add detail on source/spec_path/patch interplay, so it is strong rather than exhaustive.

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

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

States a specific verb and target ('Open a vehicle or design in the interactive 3D viewer in the player's web browser') plus the outcome ('so they can orbit and inspect it themselves'). It explicitly names the sibling it is not ('use inspect_view or the preview tools to look yourself'), so an agent can distinguish it without opening a schema.

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

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

Explicitly says the agent cannot see the rendered window and names the alternatives (inspect_view, preview tools) with the condition that selects them. It also states which condition requires body_id, giving concrete when-to-use routing for the main optional parameter.

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 and destructiveHint=false annotations, the description adds meaningful behavioral context: it says the tool tests suggested edits without changing the draft, returns each finding's severity, affected ids and explanation, and indicates which issues are automatic repairs versus requiring a design choice. It also makes the repair_vehicle handoff explicit.

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 compact sentences and front-loads the core action before explaining the return data and next step. The final 'Read-only' phrase is slightly redundant with the annotations but does not undermine the efficient structure.

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 that annotations cover safety, the schema fully describes the single input, and an output schema exists, the description provides enough context for an agent to understand the tool's role, its read-only behavior, and how to use its output. No essential invocation context 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 is one parameter, design, and its schema description has 100% coverage, including where draft names come from. The tool description does not add any further meaning about the design parameter beyond referring to 'a draft's faults', so the schema does most of the work.

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: diagnose a draft's faults and test suggested edits, wires and pipes without changing it. It also distinguishes the tool from the sibling repair_vehicle by making clear this is the read-only planning step whose output is passed onward to repair_vehicle.

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 usage context by instructing the caller to pass the returned revision, plan_id and finding ids to repair_vehicle. It does not explicitly compare against other diagnostic siblings such as preview_vehicle_diagnostics or preflight_vehicle, so it stops short of full when-to-use/when-not guidance.

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

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

Goes well beyond the annotations: it discloses the default output shape (faults only, each once), what detail=true expands to, that a missing check's detail names expected vs. actual connectivity, and critically that "connected geometry still needs testing in game" — an honest limit on what a pass means. Annotations only cover read-only/idempotent safety.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the default output behavior, with caveats and the handoff to plan_vehicle_repairs at the end where they belong. The middle enumeration of check categories is dense but each item adds discriminating information; a small amount could be trimmed.

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

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

An output schema exists and annotations cover safety, so the description only needs to frame invocation and interpretation — which it does: when to run, what the default vs. detailed output means, how to read a failure, and the limits of a pass. Nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substance: detail=true is enumerated as configuration_checks, gearbox_configuration_checks, wheel_direction_checks and repair operations, not just "every check." The design parameter's provenance is left to the schema's own description.

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

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

States a specific verb (check/validate) applied to a named resource (a draft's connected systems), then enumerates the exact subsystems covered: fuel/air/exhaust/radiator paths, driveline, electrical power and controls. This is far more specific than siblings like analyze_vehicle or score_vehicle, and the parenthetical about boats with no clutch/gearbox shows domain precision.

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?

"Run it after wiring or routing and before saving" gives a clear lifecycle position, and "plan_vehicle_repairs turns its findings into fixes" routes the agent to the corrective follow-up. It does not contrast with preview_vehicle_diagnostics or prepare_vehicle_validation, so the sibling choice remains partly implicit.

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

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

Goes well beyond the destructiveHint/not-idempotent annotations by disclosing that it refuses vehicles it did not write, only replaces its own with overwrite=true, that checks start pending, and that connected geometry never counts as game evidence. These are non-obvious side effects an agent could not infer from the schema.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and the SHA-256/revision scoping are front-loaded, followed by the usage routing and caveats. Sentences are dense but every one carries information; only the trailing 'checks start pending' sentence feels appended rather than structured.

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 write tool with annotations and an output schema present, the description covers what gets written, what is refused, overwrite semantics, the validation artifact produced, and the follow-up tools. 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 coverage is 100%, so the baseline is 3, but the description adds contextual meaning to overwrite by tying it to the ownership rule ('replaces its own only with overwrite=true'), which explains the practical consequence of the flag rather than restating its definition.

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

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

States a specific verb and outcome: exports a draft as a separate test vehicle in the game folder and opens a seven-check in-game validation run. The scope (tied to the file's exact SHA-256 and draft revision) makes it unambiguously distinct from sibling tools like save_vehicle or record_vehicle_validation.

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

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

Explicitly names the condition for use ('when a draft is ready for the player to test') and routes to both follow-up siblings by name, record_vehicle_validation and get_vehicle_validation. The refusal/overwrite rule further clarifies when the tool will and will not act.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavior: meshes come from installed components, footprint fallbacks are reported, and articulated vehicles render only the largest body unless body_id is set. 'Read-only' merely repeats the annotation and the return-image details are thin, but the fallback and articulation notes are genuinely non-obvious.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and output in the first sentence, then layers routing and caveats. The later sentences are semicolon-chained and slightly scattered ('inspect_view points a camera at one detail; drafts use preview_vehicle. Read-only.'), and 'Read-only' is redundant with annotations, but nothing is 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?

No output schema exists, so the description must characterize the return value; it does ('the image plus a size and part summary'). Combined with fallback-reporting and articulation notes, this is nearly complete, though it says little about error cases (missing vehicle, unresolvable Workshop ID) for a tool that depends on external installed content.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining the runtime consequence of body_id (articulated vehicles default to the largest body alone) and by situating body_id in the study/inspection workflow. It does not add renderer or source semantics beyond the schema, keeping it from 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?

States a specific verb and resource ('Render a vehicle') plus the two source scopes (player's vehicles folder, installed Workshop item) and the output (image plus size and part summary). It distinguishes itself from siblings by naming preview_vehicle (drafts) and inspect_view (single-detail camera) as different 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?

Gives a concrete use case ('study the player's existing boats') and explicit routing: drafts go to preview_vehicle, single-detail framing goes to inspect_view. The condition selecting body_id (articulated vs. largest body) is also given, so the agent knows when to supply it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description reinforces it with "Nothing is written" but adds little beyond that. It does add genuine behavioral context by describing the returned image views and text-summary fields and the spec-source precedence order, though it omits cost/latency expectations for rendering (e.g., whether gpu/flat trade-offs matter for iteration speed beyond the schema's own note).

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each carrying distinct load: what it returns, how it fits the design loop with named alternatives, and the no-write/spec-precedence facts. Purpose and return content are front-loaded; nothing is repeated from the schema verbatim.

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?

No output schema exists, but the description compensates by enumerating the returned views and summary fields. With all 6 parameters documented and the precedence order stated, the remaining gap is small: it doesn't say what happens when no spec source is supplied at all (default preset? error?).

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

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

Schema coverage is 100% with detailed per-parameter descriptions (spec merging, patch JSON-Patch example, design/preset name sources, renderer modes), so the baseline is 3. The description adds value by stating the precedence rule as an ordered chain — "preset or design, spec_path, spec, patch" — which lets an agent reason about override behavior without inferring it from individual field docs.

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?

Specific verb+resource ("Build a hull and return a preview image") plus an explicit enumeration of what the output contains (5 views, size, part counts, deck heights, flotation, bench fit, warnings). It clearly distinguishes itself from inspect_view (single close-up) and preview_interior (rooms), so an agent can route without opening schemas.

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

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

States the workflow explicitly ("This is the design loop: preview, compare the image with the player's brief, adjust, repeat, then save_hull") and names the alternatives with the condition that selects them (inspect_view for one large close-up from any angle, preview_interior for rooms). When-to-use, when-to-use-something-else, and the terminal action are all covered.

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/idempotentHint/non-destructive, and the description reinforces that with 'Nothing is written.' Beyond the annotations it adds genuine behavioral detail: what the rendered output contains and the cropping rule for floors above the main deck. It does not cover cost/performance or output format, which keeps it below 5.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and output, followed by usage and a caveat; three sentences with little waste. The middle parenthetical listing report contents is dense but earns its place. Minor redundancy between 'Nothing is written' and the readOnly annotation.

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?

No output schema exists, and the description compensates by describing what the preview and report contain, including the per-room fields and the main-deck cropping behavior. Adequate for a zero-required-parameter preview tool; only the concrete return medium (image vs. text report) is left implicit.

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 each parameter is documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond referring readers to hull_design_guide for spec fields; it neither explains merge precedence (schema covers) nor lists presets/designs in text.

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

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

States a specific verb (render) and resource (interior cutaway) and enumerates exactly what is produced: a centreline section, a labelled deck plan per room level, and a per-room report with named fields. It explicitly separates itself from preview_hull ('shows the outside'), so an agent can distinguish the two without opening either schema.

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

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

Gives a clear precondition ('use it after adding `interior` to a spec') and points at the guide topic that produces that input. It also names the relevant alternative, preview_hull, and what it covers. It stops short of stating when not to use it (e.g. when a spec has no interior), so not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the trailing "Read-only" adds nothing. What the description does add is genuinely useful: paint and wheel poses are approximate and the output is not an in-game screenshot, which sets expectations for a render tool. It stops short of covering render cost, resolution or the format of the returned notes.

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?

Four short sentences, front-loaded with the core action and output, then routing, then fidelity caveats. The trailing "Read-only." is redundant with annotations and is the one phrase that doesn't earn 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?

Covers what it renders, what it returns (image plus notes), how to steer the camera, how to inspect internals, which sibling to use for other design sources, and the fidelity limits. With no output schema, the brief "image plus notes" note is enough to set expectations for an agent calling an 8-parameter render tool.

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

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

Schema coverage is 100% with per-parameter descriptions including camera angle conventions, so the baseline is 3. The description adds use-case semantics the schema doesn't — that yaw/pitch/zoom/focus are meant to be combined for a close-up and that layer=components hides bodywork to expose seats, tanks and powertrain.

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

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

States a specific verb and resource ("Render a draft ... with installed component meshes and return the image plus notes") and scopes the accepted design types (imported, land, edited hull). It explicitly distinguishes itself from preview_hull and preview_game_vehicle, so an agent can pick the right preview tool without opening a schema.

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

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

Names two alternatives with the exact condition that selects each: hull specs go to preview_hull, vehicles in the game folder go to preview_game_vehicle. It also gives an in-tool routing hint for close-ups via yaw/pitch/zoom/focus and layer=components for hiding bodywork.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so extra credit is for context they cannot carry, and the description supplies it: the exact color semantics of the overlay, the fact that it returns both an image and the preflight report, and the coordinate frame ('Coordinates are draft blocks'). The 'Read-only' restatement is redundant but harmless.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and output, then usage, then the alternative route, then the coordinate caveat. The overlay legend is dense but each item is load-bearing for reading the image; no filler sentences.

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

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

Output schema exists, so return values need not be explained, yet the description still flags that both an image and the preflight report come back. With rich annotations, 100% param coverage and an explicit sibling alternative, an agent has everything needed to call this correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns one extra by adding a coordinate-space guarantee ('Coordinates are draft blocks') that is not in any parameter description and that matters when interpreting the rendered output. It does not otherwise add per-parameter guidance on yaw/layer/pitch, but the schema already handles those thoroughly with defaults and enums.

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

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

States a specific verb and resource ('Render a draft with its preflight faults drawn over it') and immediately fixes what makes this render different from plain vehicle previews: the faults overlay. The color-coded overlay legend and the explicit tie to preflight_vehicle's findings let an agent separate this from preview_vehicle, preview_hull, preview_interior and preview_game_vehicle without opening any schema.

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

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

Gives an explicit when-to-use ('Use it to see where preflight_vehicle's findings are') and names the alternative along with its argument signature: 'open_in_viewer(design=..., diagnostics=true) gives the player an interactive version.' The selection rule (diagnostic overlay vs. interactive player view) and the upstream producer (preflight_vehicle) are both 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety bar is met elsewhere. The description adds real context beyond that: results are paged by component, link ids are stable, coordinates are uncentred integer blocks, and endpoints take the forms {part_id,port} and {part_id,surface_index}. Not quite a 5 because pagination mechanics partially repeat the schema's limit/offset docs.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the returned content, then prerequisites, then endpoint formats and the sibling contrast. No filler, no redundancy, every clause carries information.

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

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

An output schema exists, so return shape needn't be restated, and annotations cover the safety profile. What remains – ordering relative to mutating tools, endpoint notation, coordinate convention, paging unit, and the geometry alternative – is all present, leaving nothing an agent needs before calling.

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%, including limit, offset and design, so the baseline is 3. The description adds no parameter-level detail beyond what the schema already documents (its 'draft' phrasing is implied by the design param).

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

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

States a specific verb and resource ('List a draft's connection points and links') and enumerates exactly what is returned: node indices, surface indices, wires with stable link ids, draft revision. It explicitly contrasts with query_parts ('lists geometry instead'), so an agent can distinguish it from the sibling without opening schemas.

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

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

Gives an explicit ordering rule: call before edit_connections, route_connections or apply_vehicle_assembly. It also names the alternative for geometry data (query_parts), so both the 'when' and the 'instead of' are covered.

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 readOnly/idempotent, but the description adds substantive behavior: coordinate units (integer blocks, 0.25 m), two different frames depending on draft origin (uncentred build frame vs. body-local for imports), the revision token contract with edit_parts, and the selection-rejection rule. These are non-obvious constraints an agent would otherwise discover only by failure.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and workflow, then constraints; every sentence carries information. The row-field enumeration is somewhat redundant against the output schema, keeping it just below top marks.

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 paged, read-only query with an output schema, the description covers the remaining unknowns: units, coordinate frames, the revision handoff, and the selection pitfall. Pagination is handled by the schema, so nothing an agent needs is missing.

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

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

Schema coverage is 100%, so baseline would be 3; the description adds real semantics on top by explaining that select can be an id selection (required for multi-voxel parts) and by introducing the revision value the caller must carry forward. It does not elaborate on limit/offset, but those are already fully documented in-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?

States a specific verb and resource ('List a draft's parts and its current revision') plus the intent ('for exact editing'), which separates it from search_parts and get_part_definition. The row contents are enumerated, so an agent knows exactly what it gets back.

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

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

Gives explicit sequencing ('Call it before edit_parts and pass its revision') and a concrete when-not rule: a selection cutting a multi-voxel part is rejected, so select its id instead. It stops short of naming search_parts as the alternative for finding parts by criteria, so not quite a full routing guide.

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 substantial behavior beyond the annotations: each observation replaces an earlier result for the same check, changed exports or mismatched hashes are refused, and the run passes only when all seven checks pass with evidence. This directly clarifies the destructive and replacement semantics implied by destructiveHint=true.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and immediately states the key exclusion. It is dense but every sentence carries relevant operational meaning.

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 rich schema, annotations, and output schema, the description is complete enough for an agent to call the tool correctly. It covers the critical validation gates and replacement behavior without needing to restate 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?

Schema description coverage is 100%, so the baseline is 3. The description still adds useful meaning by clarifying that observations are human-only, that each replaces a prior result for the same check, and that evidence is required for the run to pass.

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: record player observations for a validation run. It clearly distinguishes this from preflight output, which is important given sibling tools like preflight_vehicle and get_vehicle_validation. An agent can tell what this tool does without opening the schema.

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

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

It gives clear usage guidance: use this for human in-game observations and never for preflight output. It also explains the validation completion condition, but it does not explicitly name the companion tools such as prepare_vehicle_validation or get_vehicle_validation in the description itself.

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 declare destructiveHint=true and idempotentHint=false, and the description adds real context beyond them: dry-run by default, the batch lands as a single undo step, stale plan/revision inputs are rejected rather than coerced, and manual findings are out of scope. That is substantive disclosure about safety, atomicity and failure modes.

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?

Four short sentences, front-loaded with what the tool does and the preview-by-default behaviour, then commit semantics, then follow-up and rejection rules. No restatement of the name and no 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 destructive, non-idempotent batch mutation with an output schema, the description covers the safety profile, atomicity, required follow-up and rejection conditions. Return values are already documented by the output schema, so nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by defining the failure semantics of plan_id/revision (stale values are rejected) and by tying 'design' to the manual-findings design-choice requirement. It stops short of explaining finding_ids selection criteria beyond what the schema already says.

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

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

States a specific verb+resource ('Apply chosen fixes from plan_vehicle_repairs to a draft') and names the upstream sibling it consumes output from. It also separates itself from the neighbouring preflight_vehicle and from manual-finding handling, so an agent can place it precisely in the workflow.

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

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

Explicitly says the default is a preview and that commit=true is the write path, plus a required follow-up ('rerun preflight_vehicle afterwards'). It also names when the call will fail (stale revisions or plans, conflicting repairs) and what it will never do (apply manual findings), which is exactly the when/when-not guidance an agent needs.

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 substantial context: routes minimize length then bends, through_blocks only replace unconfigured/unlinked 01_block parts while retaining paint and restore on removal, routes never join unrelated pipe networks, and commit=true keeps one undo step. That is exactly the mutation-impact detail an agent needs beyond the hints.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and the sibling alternative, and nearly every sentence carries unique rules (colour table, block restoration, revision/return behavior). It is a dense wall of prose, though, and would read better as short grouped clauses rather than one block.

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

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

There is no output schema, yet the description covers returns (pipes added per route, warnings, new revision), the preview flag's effect on return payload, and the stale-revision rejection rule. Nothing needed to invoke a 5-parameter mutation 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?

Even at 100% schema coverage, the description adds meaning the schema cannot: bounds/waypoints are integer block coordinates, pipe_style auto resolves to enclosed for through_blocks and exposed elsewhere, color overrides the ISO 14726 content colour-coding, and the remove op shape is spelled out. This substantially 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?

Opens with a specific verb and resource: "Lay physical pipes between transmission faces in a draft," plus scope constraints (preserving access and structure). The second sentence explicitly sets it apart from the sibling edit_connections, which handles wires.

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?

Explicit routing rules: wires go to edit_connections, removal goes through query_connections with {op:'remove',route_id} then reroute, and branches on clutch/gearbox ports require an explicit T-piece rather than multiple route entries. When-to-use and when-to-use-something-else are both stated.

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

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

Annotations already declare destructive=false? No, destructiveHint=true and readOnlyHint=false, so safety profile is known. The description adds valuable specifics beyond that: it refuses names owned by vehicles it did not write, replaces its own earlier save only with overwrite=true, and returns file path, part count, and summary. It does not cover failure modes such as invalid spec handling, but the key side effects are well disclosed.

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?

Four sentences with no filler, front-loading the main action, then routing guidance, then safety constraints, then return values. Every sentence adds distinct value.

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

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

Output schema exists, so the description need not explain return values, but it briefly does anyway. It covers the critical precondition (preview approved), the alternative tool, and overwrite/collision behavior. A minor gap is not naming the preview tool explicitly, though siblings make this 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?

Schema description coverage is 100%, so all seven parameters are documented in the schema. The description adds only a usage example and a mention of overwrite=true, so the schema does the heavy lifting; 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?

States a specific verb and dual resource: writes a hull XML with thumbnail into the Stormworks vehicles folder and stores the spec as a design. It explicitly distinguishes itself from save_vehicle, so an agent can route correctly without opening either schema.

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

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

Explicitly says to use it once the preview is approved and names the alternative for drafts edited part by part: save_vehicle for imports and land vehicles. The overwrite condition is also stated, leaving no routing ambiguity.

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

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

Annotations already declare destructiveHint=true and non-idempotence, but the description adds the crucial policy detail: it refuses names claimed by vehicles it did not write and the imported original even when overwrite=true, and only replaces its own prior saves. It also discloses the return payload (file path, part count, notes), which is exactly the behavior an agent needs before a destructive write.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the action and destination, then usage, then safety rules, then return shape — no filler. The refusal sentence is densely packed and the phrase 'the imported original' takes a moment to parse, which keeps it just shy of ideal.

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 an output schema exists, the description need not detail return values, yet it summarizes them for orientation. Combined with the write policy and the part-by-part vs. hull-spec distinction, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning to overwrite by spelling out the two-tier replacement rule (own saves vs. foreign files and the imported original). The name-collision semantics are clarified beyond the schema's shorter wording.

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

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

States a specific verb and resource (write a stored draft into the Stormworks vehicles folder as <name>.xml with a Load-menu thumbnail) and explicitly differentiates itself from the sibling save_hull. An agent can tell exactly what artifact this produces without inspecting 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?

Explicitly names the use case (drafts edited part by part: imports, land vehicles, edited hulls) and the alternative (save_hull is the shortcut for a hull spec). It also states the preconditions that cause rejection, so the agent knows when the call will succeed.

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, idempotentHint and destructiveHint=false, so repeating 'Read-only' earns little. The description does add genuine behavioral context beyond annotations: results are hints about where a metric falls outside the reference min-max, and references vary in size and purpose so a miss is not a defect verdict. It does not cover failure modes such as a missing or empty reference set.

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?

Four sentences, front-loaded with what is compared and against what, then result semantics, then the caveat. Minimal waste; the trailing 'Read-only.' duplicates the annotation rather than earning its place.

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

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

With an output schema present, return values need not be explained, and 8 parameters are fully covered by the schema. The description supplies the comparison model (min-max of same-kind references) and interpretation guidance. Slightly incomplete on how kind is resolved and what happens with an empty or mismatched reference set.

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 organization beyond individual param docs by framing the input as three alternative modes (saved vehicle by name, draft/stored design, or hull spec/preset) plus the shared reference set, which helps an agent assemble a valid combination. It still leaves the kind parameter's default-detection behavior and patch ordering to the schema.

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

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

The description names a specific verb+resource: compare a saved vehicle, design, or hull spec against a reference set from study_references, with per-metric min-max checking. An agent can tell this is a benchmarking/scoring operation rather than a build or validate one. It does not explicitly distinguish itself from analyze_vehicle, analyze_hull, or preflight_vehicle, which are the nearest 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?

Usage is implied rather than stated: you compare against a set saved by study_references(save_as=...) to see where metrics fall relative to peers. The caution that 'a miss says where to look, not that the vehicle is broken' is helpful framing for interpreting results. However, there is no explicit when-to-use vs analyze_vehicle/preflight_vehicle guidance and no stated prerequisites (e.g., needing an existing reference set).

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 readOnly, idempotent, non-destructive, closed-world, so the trailing 'Read-only' is mostly redundant. The description does add real context the annotations cannot: only *installed* components are listed, results include footprint and actual connection port data, and output is paged. It stops short of noting page-size caveats or ordering, but that 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?

Three tight sentences with the capability statement front-loaded ahead of alternatives. The closing 'Read-only.' duplicates annotations and is the one expendable clause.

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

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

Output schema covers return values and annotations cover the safety profile, so the description only needs purpose, scope and routing — all present. Nothing an agent needs in order to call this correctly against its 50+ siblings 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%, including the category enum and the offset paging hint, so baseline is 3. The description's 'by family' phrasing implicitly maps to category and 'with paging' to limit/offset, but adds no syntax or format detail 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?

States a specific verb and resource ('List installed components useful for land builds') plus the return payload (footprints and actual connection ports) and paging support. It explicitly distinguishes itself from the whole-catalogue sibling search_parts, so an agent can choose without opening a schema.

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

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

'Use it to choose parts for a land draft' gives the triggering context, and the following sentence names the alternatives and the condition that selects them: search_parts for the whole catalogue without families, get_part_definition / get_part_orientation for single-part detail.

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?

While annotations cover the safety profile (readOnlyHint), the description adds crucial operational behavior not in the schema: specifying the returned data structure ('id, display name, size, and mass') and the pagination mechanism ('total and next_offset for paging').

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 text is highly dense but exceptionally efficient. Every sentence contributes to defining the scope, functionality, or placement within the broader toolset, avoiding filler while maintaining readability.

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 complete for a highly contextual tool. It covers what data is returned, how it is paginated, how it integrates into a multi-step workflow, and exactly which other tools it should or should not be used alongside.

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

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

With 100% schema coverage, the description is not strictly required to detail parameters. However, it adds semantic clarity by explaining that the search is case-insensitive and can target either the definition ID or the display name, which adds value beyond the schema definition.

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