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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the safety profile is free. The description adds genuine behavioral detail — LOCKED rows name the granting schematic, and the plan mode returns per-recipe status plus machine/MW/raw-input deltas — but says nothing about result size, ordering guarantees, or what happens when the item is unknown.

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 behavior and only two short paragraphs, no filler. Slightly harmed by telegraphic phrasing ('alternates first, marked HAVE/LOCKED against the save') that costs a re-read.

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?

Six parameters with no output schema and four undocumented fields; the description does not explain what a row actually contains, how `save`/`as_of`/`world` interact, or what `include_locked=false` hides. For a tool whose whole value is the shape of its rows, that is a meaningful gap.

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

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

Schema description coverage is only 33% (only `plan` and `as_of` are documented). The description partially compensates by explaining plan-mode deltas and the save-relative HAVE/LOCKED marking, but `world`, `save` vs `as_of` distinction, and especially `include_locked` (default true) are left entirely unexplained.

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

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

States a specific verb+resource: it enumerates every recipe that produces a given item, ordered alternates-first, with HAVE/LOCKED flags. That distinguishes it from recipe_detail or search_recipes, though the HAVE/LOCKED vocabulary is domain jargon used without definition.

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

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

It explains what happens if you pass `plan`, but never says when to choose this over nearby siblings such as compare_recipe_options, recipe_detail, or trace_upstream. No exclusions or preconditions are given.

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

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

Annotations already establish that this is a safe, idempotent, read-only operation. The description adds substantive behavioral context beyond the annotations: qty is interpreted as a rate per minute, the result is LP-solved rather than tree-expanded because recipe cycles lack a safe depth, and each row names its chosen recipe. It does not cover pagination, save pinning, or output shape, but it meaningfully improves understanding of the computation.

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: the first sentence states the core output, and the second explains the important qty and LP-solving semantics. 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?

This is a complex 11-parameter planning tool with no output schema and very low schema description coverage. The description covers the central BOM concept and qty semantics but omits most parameter behavior and does not describe return structure, pagination, save pinning, or outlet/sink handling. It is not complete enough for reliable invocation across all provided parameters.

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 only 18% across 11 parameters, so the description needs to compensate but does not. It explains that qty is a rate per minute and that the calculation is for an item, but it leaves save/as_of, world, limit/offset, outlets, allow_sinks, only_recipes, and exclude_recipes unexplained. The note that alternates change totals hints at recipe selection but does not document the filtering parameters.

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

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

The description identifies the resource clearly: a flattened bill of materials for an item at a given qty/min, including raw and intermediate rates, chosen recipes, and machines per row. It also distinguishes the LP-based approach from tree expansion. It does not explicitly name a sibling alternative, but the purpose is still clear.

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

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

The description implies that the tool is used to calculate a bill of materials for an item at a rate per minute. However, it gives no explicit when-to-use guidance, no exclusions, and no comparison to relevant siblings such as trace_upstream, recipe_detail, compare_recipe_options, or plan_factory.

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, non-destructive and non-open-world behavior, so the bar is lower. The description adds genuine context: it reports ownership/commitment state plus machine holders, and discloses a conditional mode where kind=shards performs a fit-check against free or slug-craftable shards.

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 dense sentences with no filler; the core output scope is front-loaded and the conditional shards behavior follows. The phrasing 'free, committed and owned' is slightly compressed, but nothing is redundant.

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 eight parameters, no output schema and only 50% schema description coverage, the description should do more: it never explains pagination (limit/offset), save/world scoping, or the shape of returned data. It covers the interesting subset (kind and plan parameters) but leaves the rest underspecified.

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

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

Schema coverage is only 50%, yet the description clarifies just three of the eight parameters (kind, plan_machines, plan_clock) and their interaction. The save, as_of, world, limit and offset parameters are left entirely to the schema, so the description does not fully compensate for the coverage gap.

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

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

The description names the resource (Power Shards / Somersloops) and the information returned (free, committed, owned, and which machines hold them), which is more specific than the opaque tool name 'boosters'. It doesn't explicitly contrast with a sibling tool, but the enumerated output scope makes the purpose unambiguous.

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

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

Usage is only implied: setting kind=shards unlocks an overclock-planning check via plan_machines/plan_clock, which hints at when this tool is relevant. There is no explicit statement of when to prefer this over siblings like inventory or hard_drives, nor any exclusion guidance.

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

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

Annotations already cover the read-only/idempotent profile, and the description adds genuinely new behavioral context: existence comes from installed map data, removal from the save's destroyed-actor list, remaining is the difference, and never-loaded placements are counted as remaining and flagged never_streamed. It omits pagination behavior (limit capped at 25, offset) and the meaning of save/as_of/world for staleness.

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 the counts before the mechanism, then mode descriptions. Dense and mostly waste-free, though the trailing provenance sentence is slightly buried and a stray blank line breaks the flow.

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 usefully sketches what each show mode returns (per-category counts, coordinate listings, distance ordering). For an 8-parameter tool with 50% schema coverage, the unaddressed save/world/as_of/pagination semantics are the remaining gap.

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

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

Schema coverage is only 50%, so the description must carry weight. It explains show modes, the near= syntax and the group category concept, but save, as_of, world, limit, and offset receive no explanation anywhere in the description, leaving several parameters semantically thin.

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 concrete verb and resource — 'Map collectibles (slugs, sloops, spheres, mushrooms, drop pods)' — and immediately states the four quantities returned (exist, taken, left, closest). None of the siblings (show_on_map, world_summary, search_resource_nodes) touch save-state collectible accounting, so the tool is unmistakable.

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 show= enumeration (census | collected | remaining | nearest) is described functionally, so an agent can pick a mode from intent. It stops short of explicit 'when not to use this' or naming an alternative sibling for related map questions.

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 readOnlyHint/idempotentHint annotations by explaining the underlying mechanic: a wave must fit headroom plus running generator output, or 'the fuse blows and stops the whole grid until reset by hand.' That consequence framing is genuinely useful context even though the tool itself is a safe read. It stops short of saying what the tool returns or that computing costs nothing.

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 statement in the first sentence, and every subsequent sentence adds domain meaning rather than filler. The hard line wrapping makes it slightly harder to scan than it needs to be, but there is no wasted 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?

Covers the domain model (waves, headroom, fuse) well for a complex 8-parameter tool, and annotations already assure it is non-destructive. However, with no output schema and no statement of what the returned plan looks like or whether it is paginated (limit/offset), an agent still lacks a picture 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?

Schema coverage is 50% and 8 parameters exist; the description names no parameters at all, so plan/save/as_of/limit/world/offset rely entirely on schema text (and several have none). It indirectly illuminates headroom_mw by explaining the headroom concept ('headroom plus the output of generators already burning'), which is real added meaning, but not enough to compensate for the undocumented half.

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: 'Startup order for a built plant: which blocks to energise in which wave.' It explicitly distinguishes itself from a build order, which separates it from build-oriented siblings like site_plan and plan_factory, though it never names a sibling directly.

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?

'Not a build order: build everything first, then energise wave by wave' clearly states the precondition and when this tool applies. It gives a strong usage condition but never names an alternative tool (e.g. plan_factory, site_plan) for the build-order case, leaving the routing implicit.

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

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

Annotations already declare this a safe, read-only, idempotent, closed-world query, so the description's job is narrower. It adds real behavioral context: each route is solved end to end (with a worked example chain) and the ranking incorporates raw cost, buildings, net power, and byproducts. It does not disclose output shape, truncation via `limit`, or ranking tie-breaks.

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 front-loaded sentences with no filler; the ranking criteria come first and the sibling contrast closes it. The 'Crude -> Alt HOR -> Diluted Fuel' example is dense domain jargon but earns its place by illustrating the end-to-end solving 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?

Without an output schema the description must convey what comes back, and it only implies a ranked list. For a 9-parameter tool at 33% schema coverage, it leaves save/world/as_of scoping, `rate`, `allow_sinks`, and ranking output shape unexplained, so it is minimum-viable rather than complete.

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

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

Schema coverage is only 33%, so the description must carry the burden, yet it only gestures at concepts already documented in the schema (`per_resource` as 'raw per unit', `outlets` as 'byproducts allowed out'). It says nothing about the undocumented parameters `rate`, `save`, `world`, `allow_sinks`, or `limit`, leaving most inputs ambiguous.

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 ('Rank whole routes to make an item by cost') and enumerates the cost dimensions ranked (raw per unit, buildings, net power, byproducts). It also explicitly distinguishes itself from the sibling `alternates_for_item`, which 'only lists recipes', so the agent can separate the two without reading 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 a clear use context (full end-to-end route comparison with cost ranking) and names the alternative tool `alternates_for_item` plus the condition that separates them. There is no explicit statement of when this tool is inappropriate (e.g. single-item lookup vs multi-route comparison), which keeps it below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the useful semantic distinction that crate contents are recoverable rather than spendable, but says nothing about pagination behavior or how the location data is presented.

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

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

Two short lines with the resource definition front-loaded and no filler. The parenthetical is efficient, though 'where to walk to' is colloquial enough to need a beat of interpretation.

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 five-parameter tool with 20% schema coverage and no output schema, the description is too thin — an agent cannot tell what save vs world do, how results are paged, or what a crate record contains beyond a vague 'where to walk to'.

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

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

Schema coverage is only 20% — only as_of is documented. With five parameters (save, as_of, limit, world, offset), the description gives no guidance on what save/world mean, the 25-item cap, or pagination via offset, so it does not compensate for the coverage gap.

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

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

Names the specific resource (crates on the ground, including death and dismantle crates) and what it returns (contents plus where to walk). That distinguishes it from inventory and collected_from_world, though the verb itself is only implied rather than stated.

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

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

The line 'Recoverable, never spendable stock' implies the use case — recovering items lost to death or dismantling — but there is no explicit when-to-use, when-not, or named alternative among the many siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description still adds real behavioural substance — terrain_m is a point reading including water surface/depth, ground and built elevations are sampled from nodes and buildings within radius_m and never averaged, and conduit counts come from the save (zero means none). What's missing is any statement about cost/latency or what happens when the point is outside known data.

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

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

The output inventory is front-loaded in sentence one and the remaining two sentences carry distinct semantics (elevation sampling, conduit counts). It is dense to the point of being cryptic in places — 'their gap is fill already stacked' requires domain knowledge — but no sentence 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?

With no output schema, the description takes on the job of describing returns and does so thoroughly (region, terrain, elevations, conduits, nearest node/field). Five optional parameters at 60% coverage leave 'save' and 'world' opaque, and there's no note on behaviour at unknown/empty locations, but the core contract is clear.

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 60%, and the description compensates by explaining what radius_m actually does (defines the sampling window for node/building elevations) and by clarifying that conduit results are save-derived counts. The 'at' and 'as_of' parameters are well documented in the schema itself, but 'save' and 'world' remain unexplained in both places.

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

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

The opening sentence enumerates exactly what the tool reports at a location (region, terrain height, sampled elevations, conduits, nearest node/field), which is far more specific than the name alone. It also implicitly separates itself from search_conduits by pointing there for the full list. It lacks an explicit verb framing ('describe/report') and doesn't contrast against near-neighbours like whereami or search_resource_nodes.

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

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

Usage is only implied: the reader infers this is the 'inspect one spot' tool from the enumerated outputs, and one alternative (search_conduits) is named for the case where you need conduit listings rather than counts. There is no explicit when-to-use/when-not, and no guidance versus whereami, factory_map, or search_resource_nodes, which overlap in scope.

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 and non-destructive; the description adds genuinely new behavior: identity-based matching by building+recipe, generators by building, extractors by node, 'busy' machines, the water-extractor count range, and the one-directional power proof rule ('nothing proven running', never 'unpowered'). It also discloses that unmatched in-ground machines are listed rather than removed. It stops short of describing the response shape or any limit behavior, so not a 5.

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

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

It is front-loaded with the core transformation and has no filler, but it adopts a compressed, jargon-heavy style ('one on another recipe is busy', 'nothing proven running') that packs several distinct rules into single lines. The density makes it slower to parse than an organized bullet-style breakdown of matching rules, stage semantics, and power rules would be.

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

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

For a 9-parameter, no-output-schema read-only analysis tool, the description covers the semantically hard parts: matching identity, range-based extractor counts, stage partitioning, the power caveat, and the billing output ('show_cost'). The main gap is that the shape of the return (per-stage deltas, machine lists, bill) is only sketched, and five of the nine parameters receive no narrative treatment.

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 67%, so the description bears partial load. It meaningfully clarifies `plan` (name, pin:N, or solve: handle) and `stage` (one stage vs. stage overview) — semantics the schema only partly carries. But it says nothing about `limit`, `as_of`, `world`, `factory`, or `biomass` beyond what the schema already states, leaving a gap that matches the mid-tier coverage.

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

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

The opening line states a concrete transformation: from the factory as built to a plan, expressed as concrete actions (UNPAUSE, SETRECIPE, BUILD) plus the power delta. This clearly separates it from plan-making siblings such as plan_factory, though it does not directly name the sibling it displaces for a given question. Purpose is specific and distinguishable, but the agent must infer the boundary with commission_plan.

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 hints at usage through 'stage=n narrows to one, stage=0 shows the stage overview of an unsaved solve' and by noting plan can be a solve: handle printed by plan_factory. However, there is no explicit 'use this when…, use X instead' statement for the many adjacent tools (plan_factory, commission_plan, bom, factory_map). Usage is implied rather than stated.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds real disclosure beyond them: overwriting an existing name replaces its machines, forget keeps the machines, rename propagates to saved plans, and dry_run previews before committing. Those are exactly the consequences an agent needs before invoking a destructive tool. It omits any mention of permissions, confirmation requirements, or what dry_run actually returns.

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?

Roughly ninety words for a 14-parameter, five-action tool is efficiently sized, and the action inventory is front-loaded in the first sentence. The telegraphic fragment style ('storage: is full storage at a line's end stock or a blockage') is dense to the point of being cryptic, and 'Ids survive moves and autosaves' sits awkwardly between action definitions.

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 14-param tool with no output schema, the description covers the five actions and the highest-risk parameters but leaves save, world, and notes unexplained, and never says what a dry_run preview produces. An agent can pick the right action but would still be guessing about scope parameters and return shape. Adequate rather than complete.

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

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

With 64% schema coverage across 14 params, the description adds meaningful semantics the schema lacks: the ordering of add → drop → prune_missing, the 'machine:<instance>' anchor form and the rule that the last machine can't be dropped, and the interpretation of 'to' for the storage action. It does not explain save, world, or notes, and does not clarify dry_run's effect per action, leaving a meaningful remainder undocumented.

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 multi-verb statement naming the resource and its scope: 'Name, amend, rename or forget a named factory (a set of machine ids), or set its storage stance.' An agent immediately knows this is the mutation surface for factory groupings, as opposed to read siblings like list_factories or factory_query. It stops short of naming a sibling explicitly, so it lands at 4 rather than 5.

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

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

The description gives good per-action selection guidance internally ('name on an existing name replaces its machines', 'amend adds, drops, then prune_missing clears gone anchors', 'rename: saved plans follow'), which is genuinely useful for choosing among the five actions. However, it never states when to reach for edit_factory versus edit_plan, plan_factory, or plan_from_factory, and gives no prerequisites or when-not-to-use conditions. Usage is implied through action semantics rather than declared.

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

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

Annotations already flag destructiveHint=true and non-idempotent, and the description adds real value on top: every edit creates a new version, base_rev is required to change an existing plan, forget is reversible via undo, and plans are never re-solved. It omits what happens on a stale base_rev (conflict behavior) and any permission requirements.

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

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

Two sentences plus a compact four-action definition list; the versioning/base_rev constraint is front-loaded before the per-action detail. No filler, though the multi-line action glossary is slightly denser than it needs to be.

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

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

For a destructive, versioned mutation with annotations present and no output schema, the description covers the semantics an agent needs to call it safely: versioning model, base_rev requirement, reversibility of forget, and no re-solve side effects. Minor incompleteness remains around the unexplained optional selectors (save/as_of/world).

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 63% and the description reinforces the meaning of version= (inverse for undo, target for restore) and the base_rev concurrency requirement. However, save, as_of, world and the required name parameter get no explanation in either place, so it only partially compensates for the coverage gap.

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

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

Names a specific verb set (rename, forget, undo, restore) and the resource (a saved plan), and adds the crucial scope statement 'Nothing is re-solved,' which separates it from re-solving siblings like site_plan or plan_factory. It stops short of naming an explicit sibling alternative, so a 4 rather than a 5.

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

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

Gives per-action semantics — rename keeps key/siting/notes, forget deletes (recoverable by undoing that version), undo inverts version=, restore sets head to version= — which is effectively when-to-use guidance for each mode. It does not say when not to use it or point at siblings such as diff_vs_save for inspection.

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 it as a safe, read-only, idempotent operation. The description adds valuable domain behavior: item balances are equalities, unconsumed byproducts cause infeasibility, and fluids must be consumed or packaged first. Return format and pagination behavior are not described, but the domain context is strong.

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

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

The purpose is front-loaded and the domain rationale is compact. The phrase 'handle too' is slightly cryptic, but overall the description is efficient and avoids unnecessary length.

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

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

For a 6-parameter diagnostic tool with no output schema, the description explains the core return concept well: which byproduct stalls the plan and what can consume it. However, it leaves several parameters and full output details unspecified, so it is adequate but incomplete.

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 only 50%, and the description does not explain the undocumented parameters such as save, limit, or world. It reinforces the concept of focusing on a byproduct or the whole plan, but does not fully compensate for the missing schema descriptions.

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

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

The description clearly states the tool identifies which byproduct makes a plan infeasible and what can consume it, including sinks and recipes. It is specific enough to separate this diagnostic tool from plan-building siblings, though it does not explicitly name alternatives.

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 phrase 'Reads an infeasible solve: handle too' gives implied context for when to use it, but there is no explicit when-not guidance or named alternative tool. Usage is inferable but not fully specified.

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/non-destructive, and the description adds genuinely useful method disclosure beyond them: floors are recovered by clustering foundation tops with no assumed pitch, sub-quarter-size decks are flagged minor, and platform indices are only stable within one save. That last caveat is exactly the kind of behavioral trap worth surfacing. It stops short of describing response payload or how pagination interacts with the index stability.

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 with no filler, leading with what the tool returns and then the default behavior and narrowing options. Slightly terse given the number of undiscussed parameters, 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?

For a 7-parameter tool with no output schema, the description defines the domain-specific semantics (floors, minor decks, platform index) well but says nothing about what save/world/limit/offset control, and does not describe the row shape beyond "one row per platform." Adequate, with clear gaps the agent must resolve from the schema alone.

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 43% schema coverage across 7 parameters, the description fills real gaps: it explains platform= as the index this tool prints, adds the stability caveat, and defines factory= as a name or single selector term. save, world, limit and offset are left entirely to the schema, which is where the coverage gap sits.

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?

"Floors of a foundation platform: how many decks and what stands on each" names the resource and the exact question it answers (deck count + contents per deck), which distinguishes it from factory_map, site_plan and factory_query. The verb is implicit and the phrasing is jargon-heavy, but the intent is unambiguous.

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

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

It states the default shape (one row per platform, largest first) and two narrowing modes (platform= for one index, factory= for one platform answered floor by floor), which implies when to reach for it. It never names a sibling alternative or an explicit when-not condition, so the agent must infer when to prefer this over factory_map or site_plan.

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

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

Annotations already establish a safe read-only, idempotent operation, and the description goes well beyond that: it defines uptime against the 300 s productivity window, enumerates the state taxonomy worst-first, explains the fluid diagnosis ladder, and describes offset paging across all tables. It does not mention cost, latency, or how 'save' vs 'as_of' select a world, which keeps it from a 5.

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

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

The purpose is front-loaded in the first line, but the remainder is a dense block of domain jargon with no bullets or grouping, making the state taxonomy and fluid ladder slow to parse. Little text is wasted, yet the presentation is hard to scan.

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-value burden and does so thoroughly: uptime meaning, state ordering, starvation back-tracking, and fluid diagnosis rung. It is weaker on parameter-level completeness and on how save/as_of pin a snapshot, leaving some agent-facing questions open.

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 only 33% schema coverage across 6 parameters, the description must compensate. It meaningfully explains factory ('a name, a selector term, or all') and offset ('pages every table at once') but leaves save, world, and limit unexplained, and does not clarify when to use 'as_of' versus 'save'.

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

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

The opening clause names a specific verb and resource: measuring uptime per machine and attributing each stopped machine's cause. That distinguishes it from siblings like power_report or factory_query. It never explicitly contrasts its own scope with those siblings, so it stops short of a 5.

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

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

It hints at routing ('factory=all sweeps', 'trace_upstream walks further') but never states when to pick this tool over factory_query, power_report, or trace_upstream. Usage context is implied by the described outputs rather than declared.

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 bar is lower, and the description still adds real substance: islands over-merge grown-together bases, belt components fragment, slabs are sharpest but miss ground-built machines, and show=slabs returns tile count, extent and elevation. That is meaningful disclosure about data quality and return shape beyond the annotations.

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

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

Three short paragraphs, signal definitions front-loaded before the comparison guidance and the show=slabs detail. Dense jargon, but every clause carries information; 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 read-only, no-output-schema tool the conceptual model is well conveyed, but half the parameters are unexplained and the description never indicates what the result looks like (e.g. how signals are grouped or paginated by limit/offset). Adequate, with clear gaps remaining.

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

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

Schema coverage is only 33% across 6 parameters, so the description must compensate. It does explain show's slabs mode and implicitly maps candidates to the three signal types and named to named factories, but save, world, limit and offset are left entirely to the (sparse) schema. Partial compensation only.

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

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

The description names the concrete signals returned (power islands base:<n>, belt components line:<n>, foundation slabs slab:<n>) plus named factories, which is far more specific than the tool name alone. It implicitly distinguishes itself from propose_factories by framing itself as the raw-signal source rather than the synthesizer.

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

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

It explicitly routes the agent: propose_factories combines the signals, and when sources disagree you carve with edit_factory using a product:, near: or slab: term. It also flags a specific mode (show=slabs lists bare platforms). It does not cover when to prefer list_factories or factory_query, 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes meaningfully beyond them: it explains nameplate vs. measured rates, the 300 s productivity window that makes an idle line read zero legitimately, that unmonitored machines are reported separately, and that offset paginates all tables jointly. That is exactly the kind of semantics an agent needs to interpret results. It stops short of covering error behavior (unknown/ambiguous factory, invalid view) or anything about the untokenized parameters.

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 lines, front-loaded with purpose, with no filler sentences. The compression is aggressive to the point of near-crypticity ("what it makes, needs, draws or touches"), 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 7-parameter read tool with no output schema, the description adequately frames what the result means (rate semantics, unmonitored machines, cross-table paging). It leaves gaps on four of the seven parameters and on failure modes when the factory selector does not resolve, which matters given how many sibling tools could be confused with 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 coverage is only 43%, so the description needs to compensate for undocumented parameters — and it largely does not. It adds real meaning for `offset` (pages every table at once) and reinforces `show`, but `save`, `limit`, `world`, and the exact selector semantics of `factory` go unaddressed in the description while also lacking schema descriptions.

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

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

The opening states a concrete scope ("One question about one factory") and enumerates the questions it answers (makes, needs, draws, touches) plus the multi-view mechanism via `show=`. It is clear what the tool returns, but it does nothing to distinguish itself from siblings like factory_health, factory_floors, factory_map, or trace_upstream that also read a single factory.

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

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

Usage is only implicit: the agent is told `show=` takes several views and that views can be combined, which implies "prefer this over multiple calls." There is no when-to-use / when-not-to-use statement, no mention of how to find a factory name (e.g., list_factories) if `factory` is unknown, and no exclusion against sibling read tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds the clustering behavior and 'largest first' ordering, which is useful, but says nothing about pagination, the effect of limit/offset, or what a caller gets back. It adds context without contradicting 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?

It is short and the core behavior is front-loaded, but the second sentence mixes selector syntax and a sibling comparison in a way that's hard to parse without prior domain knowledge. Nothing is padded, though some wording (e.g., 'Built production buildings') is awkward rather than economical.

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 five parameters at 20% schema coverage and no output schema, the description carries a heavy burden and doesn't meet it: save, world, limit, and offset go unexplained, and return shape beyond ordering is unstated. The selector guidance is helpful but disconnected from the actual input 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?

Schema description coverage is only 20% – just as_of is documented. The description explains select= and factory= selector syntax, but neither appears among the five actual parameters (save, as_of, limit, world, offset), so the only parameter detail offered doesn't map to the schema. The remaining four parameters receive no meaning from either source.

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

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

The description states the result shape (production buildings clustered by distance into sites, largest first) and names a sibling, propose_factories, that differs. However, it never uses an explicit verb such as 'list' or 'find', so the action itself is only implied. An agent can infer this is a retrieval tool but not with full confidence from the description alone.

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 notes that propose_factories groups by more than distance, which implicitly guides selection, and explains where a near: selector goes. It stops short of stating when-not to use this tool or what prerequisites exist, leaving the comparison 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is covered. The description adds useful content about what each entry reports (shortages, open goals, raw saved, grid MW) and that `sources=` triggers an additional solve 'as plan_factory does' — genuinely beyond the annotations. It still omits how the solve interacts with pagination or how expensive that call is.

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?

Very short and front-loaded, with the primary resource stated first and the modifier behaviors immediately after. It earns most of its length, though the telegraphic fragments ('Measured on this world: shortages, open goals, raw saved on what is built, grid MW') are terse to the point of being hard to parse for an agent unfamiliar with the domain.

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 7 parameters, no output schema, and only 43% schema coverage, the description needs to carry more. It leaves `save`, `world`, `limit`, and `offset` unexplained and never says what the response looks like or how pagination/default of 25 affects the 'unclaimed' claim. An agent can invoke it, but not confidently reason about the results.

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 43%, so the description should compensate — and it only explains `drive` and `sources`, both of which already carry schema descriptions. The undocumented parameters (`save`, `world`, `limit`, `offset`) are left with no semantics anywhere; notably the interaction between `save` and `as_of` (pinning a save) is never clarified in the description even though `as_of` hints at it.

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 core purpose is discernible: enumerate unclaimed hard drives with a recommended pick and rationale, plus a detail mode via `drive=N`. However, no explicit verb is used ('Unclaimed hard drives' is a noun phrase), and the second paragraph stacks unrelated capabilities (shortage metrics, build-out solve) onto the description, blurring what the tool primarily does. It does name a sibling (`plan_factory`) for the solve behavior, which helps differentiate.

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 only through parameter hints: 'drive=N details one drive' and 'sources= adds a build-out solve.' There is no explicit statement of when an agent should reach for this tool versus siblings like `rank_unlocks`, `plans`, or `propose_factories`, and no stated prerequisites or exclusions.

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

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

Annotations already declare the mutation profile (not read-only, not destructive, not idempotent), so the bar is lower. The description adds that the result is a new plan (i.e., source is copied rather than mutated), but says nothing about duplicate-name handling, save/world interactions, or 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?

A single front-loaded sentence with no filler. Compact and easy to parse, though correspondingly thin on required context.

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 mutating, non-idempotent tool with five parameters, no output schema, and two undocumented parameters (save, world), the description is too sparse. It doesn't tell the agent what the import returns, how save/world affect the copy, or what happens on name collisions.

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 60%. The description restates the input forms already documented for the text parameter ('link, sfplan: line or file'), adding no new detail. The save and world parameters have no schema description and are not explained in the description either.

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 (Import) and resource (a shared plan), plus the supported input forms and the outcome (a new plan). It is clear enough to distinguish from share_plan, though it doesn't explicitly contrast with siblings like plans or plan_from_factory.

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?

No guidance on when to use this versus alternatives such as plans, share_plan, or plan_from_factory, nor any preconditions or exclusions. The only implied usage is 'when you have a shared plan to import.'

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), so the description's job is domain semantics — and it delivers: `spendable` is defined as carried + storage + Dimensional Depot, machine buffers and crates are explicitly excluded from that sum, and fluid units are stated as m3. These are non-obvious aggregation rules an agent could not infer from structured fields. Return shape is only implied, not stated.

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

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

Front-loaded with the two modes, then the aggregation rule, then the unit note, then the per-parameter scoping — a sensible information order with no filler. The telegraphic phrasing ('place and fill', 'shown apart, never added in') is dense but readable. Slightly clipped style costs it the top mark.

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 11 parameters and no output schema, the description does the important work: it sketches what each view returns (per-item totals; per-container with place and fill) and defines the spendable aggregate. Enough to call it correctly for the common cases; the undocumented `save`/`world`/pagination parameters are the residual gap.

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

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

Schema coverage is 55%, so the description must compensate, and it does for `item`, `show`, `near`, `container_kind` and `empty` by tying them to views. However `save`, `world`, `limit`, `offset` and especially `radius_m` (clearly coupled to `near`) carry no explanation anywhere, leaving a meaningful gap in a mutation-free but 11-parameter 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?

Opens with a concrete verb-and-resource framing ('What you own') and immediately enumerates the two output modes: per-item totals vs per-container/crate/fluid-buffer listing. An agent can tell this is an ownership/inventory query and not a plan or factory tool. It stops short of naming a sibling (e.g. `crates`) it might be confused with, which keeps it from a 5.

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

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

Explicitly states the mode switch (`show=containers`) and then scopes which parameters apply to which view: `item=` narrows either view, while `near=`, `container_kind=` and `empty=` are containers-only. That is real routing guidance an agent can act on. No exclusions or alternative-tool pointers are given, so not a 5.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds real context: results are marked HAVE/LOCKED relative to a save, `logistics` additionally reports the fastest unlocked belt and pipe, and `all` returns hundreds of rows (a performance caution). It stops short of describing return shape or ordering, so it is strong but not complete.

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

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

Three tight sentences with no filler, and the high-value facts (what is returned, the `all` cost) are front-loaded. It is dense and jargon-heavy enough that a first-time agent may need a second pass, 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?

With six parameters, low schema coverage, and no output schema, the description does well on output attributes and pagination but leaves the three save-identifying parameters (`save`, `as_of`, `world`) and `limit` unresolved. For a tool where selecting the wrong save scoping could silently return the wrong data, that gap matters.

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 33% with only `as_of` and `building_kind` documented, so the description carries extra burden. It does clarify offset-based paging, the cost of `building_kind=all`, and the special behavior of `logistics`, plus hints at the save linkage via 'against the save', but `save`, `world`, and `limit` remain unexplained and the save/as_of/world relationship is ambiguous.

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

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

The description states the resource and the attributes returned per building kind (power, max clock, sloop slots, footprint) with HAVE/LOCKED status against the save, so the agent knows it enumerates buildings filtered by kind. The verb 'list' is only implied by the name rather than stated, and no sibling (e.g. factory_query, factory_map, list_factories) is contrasted, which keeps it below a 5.

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

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

Usage is only implied: the note that pages are paged with offset= and that `all` is hundreds of rows gives practical guidance about when to paginate or avoid `all`. There is no explicit statement of when to reach for this tool over factory_query or factory_map, nor any prerequisites.

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 profile is covered. The description adds two behavioral facts: results are scoped to the current world, and each entry includes a degradation/status figure. It says nothing about ordering, pagination, or what happens for worlds with no factories.

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

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

A single front-loaded sentence with a clarifying parenthetical; nothing is padding. The closing phrase 'how much of each still stands' is evocative but slightly vague about the actual metric returned.

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?

Adequate for a simple zero-required-parameter read with no output schema, and it does communicate the return shape at a high level. However, with three optional parameters whose interplay (current vs. pinned world/save) is unexplained, an agent still has to guess about defaults and scope selection.

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

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

Only 33% of the schema is documented (as_of alone), and the description does not compensate: the 'world' parameter is only obliquely gestured at via 'this world', and 'save' is never mentioned or distinguished from as_of, even though both appear to be optional save-pinning knobs. An agent cannot tell from this text what leaving them null does.

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 named factories) scoped to 'this world', and adds that each entry carries a completeness/status measure ('how much of each still stands'). It implicitly distinguishes itself from siblings like factory_health or factory_query by returning names plus status, though it never names those siblings explicitly.

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

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

The parenthetical '(the names factory= takes)' is a useful usage cue: call this to discover the factory identifiers other tools expect. But there is no explicit when-to-use/when-not guidance and no named alternative among the many factory-related siblings (factory_map, factory_sites, factory_query).

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 that this is a safe, read-only, idempotent, closed-world operation. The description adds meaningful behavioral context beyond that: region names are advisory with roughly 256 m boundaries, and the anchor is guaranteed to lie inside the region.

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

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

The definition is compact and front-loads the core output description before the filter behavior and the two caveats. Every sentence adds useful information, with no repetition or filler.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers the returned fields, the filter behavior, naming caveats, and the anchor guarantee. It could be slightly more complete with ordering or pagination details, but the essentials are 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 0%, so the description must carry the burden for the single optional parameter. It does so by explaining that `resource=` keeps only regions containing that resource, which gives the parameter clear filtering semantics beyond the bare string/null schema.

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

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

The description clearly identifies the resource as named map regions and lists the returned attributes: anchor coordinate, area, and node count. It also mentions the resource filter, but does not explicitly differentiate this tool from nearby siblings such as show_on_map, describe_location, or factory_map.

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

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

It explains the semantics of the `resource=` filter, but gives no explicit guidance on when to call this tool versus alternatives or when not to use it. The note about `region:<name>` selectors is useful context, yet it is not framed as usage guidance.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond that: grouping by world, newest-first ordering, default selection of the newest save, and pagination via offset.

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 short and front-loads the grouping/sort behavior, but the phrase 'the names save= and world= take' is awkward and introduces an unexplained parameter name. It is concise but not cleanly 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 simple two-parameter read tool with no output schema, the description covers grouping, sorting, default behavior, and pagination. It still leaves ambiguity about the response shape and the nonexistent 'save=' reference, so it is only partially complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains world= and offset= somewhat, but also references 'save=' even though no save parameter exists in the schema, creating confusion for the agent.

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

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

The description states the core result: saves grouped by world, ordered newest first. It is clear enough to understand what the tool returns, though it does not explicitly say 'list' and does not distinguish itself from siblings like world_summary or plans.

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 parameter-driven usage hints: world= lists one world's saves and offset= pages them. However, it provides no explicit guidance on when to choose this tool over alternatives such as world_summary or list_factories.

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 behavior. The description adds a genuine data-quality caveat (deprecated per-phase item table; trust the header line), which is context beyond annotations. However, it doesn't mention what the tool returns, whether 'save' defaults to the current save, or how 'as_of' pinning affects the answer.

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

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

Two short sentences, front-loaded with the resource and payload; no wasted clauses. The only weakness is that its brevity leaves important details out, but it isn't 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?

No output schema exists, so the description should describe the return shape (current phase name, item list?) more explicitly. With three optional parameters of ambiguous semantics and no guidance on defaults or save pinning, an agent lacks enough to call this confidently without inspecting the schema and experimenting.

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 only 33% (only 'as_of' is documented). The description adds no meaning for 'save' or 'world' — it only vaguely references 'the save's per-phase item table' without explaining how to supply or resolve a save. With low coverage, it should compensate but doesn't.

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

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

States the specific resource (Space Elevator current phase) and payload ('what it still wants'), which is concrete enough for an agent to know what it returns. No sibling tool overlaps this topic, but the description doesn't explicitly differentiate from alternatives like research or plans. Minor gap: no explicit verb.

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?

No indication of when to call this versus alternatives, no prerequisites, no mention of the save/as_of/world interplay. The sentence about the deprecated per-phase item table is a data-trust warning, not usage guidance. The agent must infer usage from the name alone.

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 significant behavior: save_as stores the request rather than the solution, base_rev is required to overwrite, the default objective depends on export_minimums, exports replace defaults with special [] and 'MW' semantics, locked required recipes are refused, and the temporary solve token is explained. It does not cover every execution or error detail, but it is substantially richer than the annotations alone.

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

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

The purpose is front-loaded and the dense notes are mostly justified for a 35-parameter tool. The telegraphic shorthand and occasional run-on punctuation reduce readability, but there is little wasted text.

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

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

For a complex LP planning tool with no output schema, it explains the key non-obvious defaults, save/overwrite behavior, export rules, and token handoff. It still omits details for several parameters and gives only broad output categories, so it is not fully complete but covers the main failure points.

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 74% schema description coverage, the description still adds meaningful semantics for high-impact parameters such as sources selector syntax, objective values and defaults, exports replacement behavior, required recipes, save_as/base_rev, and plan recall. Many of the 35 parameters are still left to the schema, so it is strong but not 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?

The opening sentence states a specific verb and resource, 'Solve a factory plan by LP', and lists the planning outputs: machines, rates, power, exports, byproducts. It does not explicitly distinguish itself from nearby plan tools such as plan_from_factory or plan_layout, so it falls short of a 5.

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

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

The description is largely a parameter manual and never says when to choose plan_factory over plan_from_factory, plan_layout, site_plan, or edit_plan. Mentioning that the answer token is for 'other plan tools' is not enough to guide tool selection.

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

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

Annotations declare a non-readonly, non-destructive, non-idempotent write, and the description adds real substance on top: recipes get pinned, inputs supplied, surplus exported under the stated flow stance, equal plans are reused, and differences are recorded in notes. The gaps are the cryptic "sunk under the flow stance" clause and no statement of permissions or what a failure looks like.

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

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

The core purpose is front-loaded in the first sentence and total length is short. But the second paragraph is dense jargon with an opaque parenthetical, so it is compact at the cost of parseability rather than genuinely efficient.

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

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

For a 5-parameter mutation with no output schema, the description covers the semantics of the write reasonably (pinning, reuse, export, notes) but leaves the return unknown and half the parameters unexplained. It is enough to avoid a wrong call, not enough to call it confidently with the right argument 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 coverage is 60%, and the description compensates for none of it: save, as_of, world, and factory are never explained (as_of's sav: token hint lives only in the schema). Worse, "Differences from the build go in the notes" references a "notes" concept that is not a parameter at all, which can send an agent looking for a field that does not exist.

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

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

"Save a plan mirroring a named factory as built, to edit or extend" specifies a concrete verb (save/mirror) and resource (a factory-derived plan) plus the intended follow-on use. It is clearly understandable without opening the schema, but it never differentiates itself from plausible siblings such as plan_factory, import_plan, or edit_plan.

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?

Phrases like "as built, to edit or extend" imply the situation (you want an editable copy of an existing factory rather than a fresh solve). However, there is no explicit when-to-use/when-not and no named alternative, even though siblings plan_factory, import_plan, and commission_plan occupy adjacent 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 cover read-only, idempotent, non-destructive, so the safety bar is lower; the description adds useful scope constraints (no coordinates, no belt routing) and the tier-consistency guarantee. However, the schema exposes a 'save' parameter while readOnlyHint=true, and the description never clarifies whether saving writes state — a gap an agent would want resolved.

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

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

Two short sentences, front-loaded with the core purpose and with zero filler. The second sentence is grammatically dangling ('is solved with, so schematic and plan agree'), which costs a point on clarity without costing much length.

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

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

For a 12-parameter tool with no output schema, the description should at least characterize the response shape, and it only gestures at it via the list of schematic categories. Combined with the unexplained 'save' parameter, there are real gaps, though the stated scope boundaries prevent the agent from misusing 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 coverage is 75%, so the baseline is 3. The description hints at the belt_tier/pipe_tier behavior ('solved with, so schematic and plan agree') and the space-budget concept behind max_floor_foundations, but it adds no semantics for plan, save, as_of, show, or order_floors_by beyond what the schema already states.

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

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

The phrase 'Plan to schematic' plus the enumeration of outputs (blocks, buses, floors, materials, space budget) tells an agent this renders a saved plan into a schematic view, and it explicitly names the boundary against site_plan. It falls short of a crisp verb+resource statement and never says what 'schematic' actually is, so an agent still has to infer the output form.

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

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

There is one real exclusion: 'no coordinates or belt routing (site_plan places it)' routes the agent to the right sibling for placement. But there is no positive when-to-use guidance, and no differentiation against plan_factory, edit_plan, plans, or factory_floors, several of which could plausibly be confused with 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds real behavior: the request view 'solves nothing', forgotten plans remain discoverable, and the v14 -> base_rev=14 mapping to mutation tools. Return shape and pagination behavior are not described.

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 list-then-single-plan distinction is front-loaded, which is good, but the second sentence is a dense run of clauses joined by semicolons and commas ('prints the stored arguments, what the selectors resolved to and the siting, solving nothing; a forgotten plan is found too') that takes effort to parse.

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

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

Seven optional parameters, 57% schema coverage and no output schema mean the description has to do real work, and it covers the two modes plus the version convention. It leaves the as_of/save pinning, limit behavior, and what fields come back for a version list unexplained.

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 57%, and the description carries the most important semantics: name selects single-plan mode and show='request' switches the view. However, save, as_of, limit, and world are left entirely to their (partly absent) schema descriptions, and 'since' is explained only in the schema. Adequate but incomplete compensation for the coverage gap.

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

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

Starts with a specific verb+resource: list this world's saved plans, or one plan's versions when name is given. The two modes are clearly delimited, and edit_plan is named as the mutating counterpart. The parenthetical 'world moved?' is jargon that only a returning user would parse, which keeps it short of a 5.

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

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

Explicitly says what show='request' is for ('prints the stored arguments, what the selectors resolved to and the siting, solving nothing') and routes renames/forgets/undoes/restores to edit_plan. It also states the cross-tool convention of passing the version as base_rev. It stops short of saying when to use this versus diff_vs_save or plan_from_factory.

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/destructive=false, so the safety bar is low; the description instead adds genuine behavioral semantics beyond them — the 300 s productivity window for measured draw, and the 'starved' state where generators with zero monitor readings are reported but their MW will not actually arrive. That starvation caveat is exactly the kind of non-obvious detail that prevents a misread of the numbers.

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?

Short, front-loaded: the comparison is stated first, then each term is defined in one clause. Dense but every sentence carries vocabulary needed to read the report; 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 no output schema, the description rightly explains the report's vocabulary (nameplate, measured, starved), which is the bulk of what an agent needs to interpret results. However it says nothing about scoping (which save/world is reported on when 'save' and 'as_of' are omitted) or the effect of toggling biomass, leaving those behaviors unstated.

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

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

Schema coverage is only 50%: 'save', 'world' and the required semantics of 'as_of' are undocumented in both schema and description. The description never mentions any parameter — not even that 'biomass' toggles whether hand-fed burners count, despite that being a visible modeling decision in the output.

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

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

The opening sentence names the exact resource pair being compared (grid generation capacity vs machine draw) plus the 'free now' headroom, which no sibling tool covers — the sibling list is all factory/plan/recipe tooling. It stops short of naming a sibling it is distinct from, but the scope is unmistakable.

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?

'what is free now' implies the use case (checking power headroom), and the nameplate/measured definitions imply the two modes of comparison. There is no explicit when-to-use, no prerequisite, and no alternative tool named, so guidance is only implied.

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

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

Annotations already cover read-only/idempotent safety, so credit goes to genuine extras: it discloses that results err toward splitting, never merge, and may return one factory in pieces. It also explains that the proposal selector is numbered across all proposals so paging does not shift it — a real behavioral caveat. No info on ordering or total counts.

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

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

Compact and front-loaded: what it returns first, then behavioral caveats, then selector mechanics and usage hooks. A few phrases ('clustered by slabs, proximity, belts, shared products and supply') are dense jargon but each sentence 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 no output schema, the description carries the burden of explaining returns; it covers the # selector column and the clustering concept but not the other fields an agent will see. Paging stability is addressed, but the overall return shape remains only partially characterized.

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

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

Schema coverage is only 29% across 7 params; the description adds meaning for unnamed_only and ties the proposal:<n> selector to results, and as_of/max_span_m are described in-schema. But save vs. world vs. as_of distinctions and limit/offset behavior are left to the schema, so it only partly compensates for the coverage gap.

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

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

States a specific verb+resource ('Proposed factories: what is built') and characterizes the clustering basis (slabs, proximity, belts, shared products/supply), which lets an agent distinguish it from list_factories. It is jargon-heavy ('slabs') and never plainly says 'infers factories from built structures', keeping it short of a 5.

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

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

Gives two concrete usage hooks: name a proposal with edit_factory, and unnamed_only=true for 'what have I built and not named'. It never contrasts with the obvious sibling list_factories, nor states when not to call it, so usage is implied rather than fully routed.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral detail: every raw scoring component is exposed for re-weighting, the score is advisory, and there is no offset so pagination must go through limit/sources. That is useful beyond-annotation context, though permissions/cost/return shape aren't discussed.

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 ranking explanation are front-loaded and dense with signal; the trailing notes on sources and pagination earn their place. Slightly verbose in the middle clause about raw components but no true waste.

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

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

For a 6-parameter read-only tool with no output schema, the description adequately covers ranking semantics, the sources selector, and pagination, but does not explain the save/as_of/world interplay that matters for result scoping. An agent could still mis-scope a call by guessing at those params.

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

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

Schema coverage is only 17%, so the description must compensate. It usefully explains `sources` semantics and the `limit`-instead-of-offset rule, but leaves `resource` (the only required param), `world`, `save`, and `as_of` — including the distinction between save and as_of — entirely 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?

States a specific verb and resource — 'Rank fields for a new extraction site of one resource, best first' — and immediately conveys the output ordering. An agent can distinguish it from search_resource_nodes, which it explicitly references as a complementary selector source.

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 condition for `sources` (narrows the area, omit for whole map) and names the sibling whose selectors it accepts. It also explains the no-offset pagination rule. What's missing is a when-not-to-use-this / alternative-tool clause beyond the sources hint.

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 behavioral context beyond that: deltas are an upper bound, candidates needing unbuilt machines are judged as if built and the machine is named, and hard-drive-pending alternates are flagged claimable now. It doesn't mention cost of the repeated re-solves or the shape of the ranked output.

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 definition followed by two short caveat blocks; every sentence carries information. The line-broken formatting is slightly ragged but not wasteful.

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

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

With no output schema, the description should explain what the ranking looks like (ordering, units, tie handling with limit), which it only gestures at via 'the plan's own units'. The behavioral caveats are good, but the parameter/save-scope story and the output form are left incomplete for a six-parameter analysis 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?

Six parameters at 50% schema coverage, and the description mentions none of them. The undocumented save, as_of, world, and limit fields get no explanation anywhere, and even the meaning of 'plan' (name vs pin:N vs solve: handle) is only conveyed by the schema, not the 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 action on a specific resource: it values each candidate locked alternate recipe relative to THIS plan by re-solving and reporting the delta. That is distinguishable from sibling listing tools like alternates_for_item or unlocked_recipes, though the description never names those siblings to make the contrast explicit.

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 by phrases like 'locked alternate recipe' and 'THIS plan', and it gives interpretation guidance ('A zero delta is an answer'), but it never states when an agent should call this instead of alternates_for_item, hard_drives, or compare_recipe_options.

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, closed-world, non-destructive, so safety is covered. The description's real contribution is disclosing the returned fields, which matters since there is no output schema, but it says nothing about what happens when a recipe is absent or how save/world scope alter the answer.

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

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

It is a single front-loaded line with no filler, which is good. But it is compressed to the point of being cryptic ('unlock source', 'in/out per minute'), so brevity costs some interpretability.

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 4-parameter lookup with no output schema and half its parameters undocumented in the schema, the description should explain save/world scoping and the multiple-save case. As written, an agent can call it but cannot predict how save and world change 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 coverage is 50%: recipe_id and as_of are documented, while save and world carry no description anywhere. The tool description does not compensate at all - it never mentions save, world, or as_of, and 'unlock source' in the field list does not clarify what those parameters do.

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?

It names the resource and enumerates the fields returned (in/out per minute, machine, cycle, power, unlock source), so an agent knows this is the single-recipe detail lookup. It never distinguishes itself from nearby siblings such as search_recipes, compare_recipe_options, or unlocked_recipes, and the verb is implied rather than stated.

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

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

There is no statement of when to reach for this versus list/search alternatives, no prerequisites, and no exclusion. The word 'One' implies single-item scope, but the agent must infer that from a fragment rather than from explicit routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description genuinely adds interpretive context the annotations cannot: READY is about the bill, a locked tier surfaces the phase that opens it, and MAM 'LOCKS' rows gate capabilities rather than recipes. It does not cover result ordering or pagination behavior behind limit/offset.

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

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

The core purpose is front-loaded and the whole thing is short, but the layout is ragged: sentences break mid-clause, 'what is left, what it costs, what spendable stock affords now' compresses three ideas without punctuation, and the trailing '`tier=` is HUB only' dangles as a stray fragment.

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, no-output-schema tool this is only partially sufficient. It does explain how to read the results (READY, LOCKS, phase_requirements), which is valuable, but leaves five parameters undefined and gives no guidance on combining `tree`, `show`, and `tier`, which is the main misuse risk here.

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 56%, so about half the parameters carry their own docs. The description only reinforces `tier=` as HUB-only, which the schema already states word for word, and only implicitly maps 'HUB milestones or MAM research' to `tree`. It never touches `save`, `world`, `query`, `limit`, or `offset`, so it does not compensate for the coverage gap.

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

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

The opening clause names both resources (HUB milestones, MAM research) and the three things it answers: what is left, what it costs, what stock affords now. An agent can tell this is a read/progress-and-cost lookup. It never contrasts itself with close siblings like phase_requirements, bom, or rank_unlocks, so it stops short of a 5.

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

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

It states one real routing constraint, '`tier=` is HUB only', and explains the pending/READY distinction via `show`/READY semantics. There is no when-to-use vs. when-not guidance, no mention of `tree=mam` vs. hub selection, and no pointer to the sibling that answers the overlapping questions (phase_requirements, rank_unlocks).

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. Beyond that, the description adds meaningful behavior: results are sorted longest first, proximity is measured against the drawn line so mid-span crossings count, and the show/network mode switches the returned entity type. Missing detail on pagination/limit behavior and default radius handling.

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

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

The description is front-loaded with the core purpose, then layers in entity definition, sort order, and alternate modes. Dense but each sentence earns its place; only mildly jargon-heavy for an unfamiliar reader.

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 12-parameter tool with no output schema, the description covers the conceptual model and main modes well but leaves several parameters (radius defaults, save/world, limit/offset) undocumented. An agent can call the core path but lacks guidance on pagination and scoping parameters.

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 only 58% schema coverage, the description compensates for the key semantic params: near (centre forms incl. run ids), to (second area, both-proximity), show modes, network=N, and conduit_kind via 'belt and pipe'. However several params (radius_m which defaults to 250, save, world, limit, offset) are unexplained in both schema and description, leaving gaps.

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

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

The description names a specific verb and resource ('Belt and pipe runs near a place or between two areas') and enumerates the exact fields returned (both ends, length, elevation, what each end connects to). It defines what a 'run' is (one belt chain or one placed pipe) and its id format, so an agent understands the entity precisely. No sibling offers conduit search, so it is naturally distinguished.

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 use contexts: 'near a place or between two areas', and explains the alternate modes ('show=networks' lists fluid networks, 'network=N' lists its pipes). It also clarifies the 'between two areas' semantics for the to parameter. No explicit when-not or comparison to other search tools, but usage is well conveyed.

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, and openWorldHint=false, so the safety profile is covered. The description adds that results include 'form, MJ and sink points,' which is useful output context, but it does not describe pagination behavior or how limit/offset affect results.

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

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

The description is very short and front-loads the main action, which is good. But the phrase 'form, MJ and sink points' is ambiguous and does not clearly earn its place without more explanation.

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 search tool with three undocumented parameters and no output schema, the description is too thin. It gives the core action and hints at returned fields, but omits pagination semantics and does not clarify parameter usage, which an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining parameters. It only implies that 'query' is an item name and says nothing about 'limit' or 'offset,' leaving the pagination parameters undocumented.

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

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

The description states a clear verb and resource: 'Find items by name.' This makes the core purpose understandable. However, it does not distinguish itself from sibling tools such as search_recipes or recipe_detail, and the trailing phrase 'form, MJ and sink points' is cryptic without additional context.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The description implies item-name lookup but does not mention search_recipes, recipe_detail, or any exclusion or prerequisite.

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/non-destructive. The description adds genuine behavioral context: results are marked HAVE/LOCKED against the save, and the header counts all recipe_kinds regardless of the recipe_kind filter — a non-obvious quirk worth disclosing. It says nothing about pagination, empty results, or save-resolution behavior.

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

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

Two tight sentences plus a header note, front-loaded with the primary capability. No filler, though the header-count sentence is buried at the end where its relevance to filtering is easy to miss.

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 11 parameters, 18% schema coverage, and no output schema, the description should carry much more weight. It covers the relational filters and the result markers but omits the meaning of include_events, only_alternates, world/save/as_of, and paging — an agent cannot confidently call this tool without guessing.

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 only 18% across 11 parameters, so the description must compensate. It clarifies consumes, produces, and their combination, but leaves save, as_of, world, query, limit, offset, include_events, and only_alternates completely undocumented in both schema and description — a large gap for a tool with this many knobs.

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 ('Search recipes') and immediately broadens the retrieval model to name or by consumes/produces relation. It doesn't explicitly contrast itself with siblings like recipe_detail or alternates_for_item, but the reverse-lookup framing is distinctive enough to separate it from a plain lookup.

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

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

The description explains the semantics of consumes= and the consumes+produces combination, which implies when each mode is useful, but it never states when to prefer this tool over recipe_detail, compare_recipe_options, or alternates_for_item. Usage is inferable rather than stated.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds meaningful behavior beyond annotations: sources union and filters intersect, printed node_ids are reusable, near adds distances, and water has no nodes.

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

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

The description is compact and front-loads the three output modes before explaining selectors. It is dense and somewhat cryptic, but nearly every phrase carries useful operational 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 complex 13-parameter search tool with no output schema, the description covers the core query modes and source syntax reasonably well. It still omits details about pagination behavior, returned fields, and several parameters, so it is only minimally complete.

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

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

Schema description coverage is only 46%, so the description must carry substantial parameter meaning. It does explain the complex sources selector and near/show behavior well, but leaves several of the 13 parameters, including save, world, limit, offset, status, and only_free, largely or entirely unaddressed.

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

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

The description clearly states that the tool returns resource nodes in three modes: clustered fields, one-row-per-node, or nearest-by-distance. It is specific about the resource and output shape, but does not distinguish it from sibling search/map tools such as show_on_map or factory_map.

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

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

It provides usage details for parameters, including that sources can be omitted for the whole map and that show=nearest requires near. However, it gives no explicit guidance on when to choose this tool over sibling tools, leaving tool selection implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds non-obvious semantics: product: selectors also pull machines feeding that product in other sites, and slab:<n> describes an empty platform rather than returning nothing. It doesn't say what the preview output looks like (counts, ids, grouping) or whether there are result limits, which is the main 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?

Short and front-loaded: the preview-vs-edit relationship lands in the first clause, with the selector-specific caveats following. The awkward line breaks and sentence fragments in the latter two sentences cost a bit of polish but nothing is padding.

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

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

There is no output schema, so the description should describe what a 'preview' actually returns; it never does. With 6 parameters and two (save, world) undocumented anywhere, an agent still has to infer scope and result shape 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 coverage is 67% and the description adds real meaning to the selector vocabulary (product:, slab:<n>), but says nothing about save, world, or how expand/split interact with the preview. Baseline 3 is appropriate since the schema carries most parameter documentation.

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 — preview which machines a selector picks — and immediately distinguishes itself from the write-side sibling edit_factory. An agent can tell it apart from list_factories or factory_query 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 clear when-to-use context ('before naming them with edit_factory', 'run it first on product: terms') and explains what slab:<n> is for. It stops short of stating exclusions or naming a non-preview alternative for inspecting machines, so it's clear context rather than full routing guidance.

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

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

Annotations already establish that this is a non-destructive, idempotent, closed-world mutation. The description adds useful behavioral context beyond that: the settings file is shared with the page's Settings tab, changes are followed there, and base map types are listed read-only.

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 constraint is front-loaded in the first sentence, and the following notes are compact and relevant. The wording is somewhat cryptic and line-broken, but it does not waste many words.

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

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

For a one-parameter settings tool with annotations and no output schema, the description is mostly adequate. It still leaves ambiguity around how current settings are read and what calling without a change returns, which matters because no output schema exists to clarify the response.

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 for specific keys such as stage_headroom, biomass, payback_hours, and overclock_last. The schema handles the shape of 'change' and its null-reset behavior, while the description explains what several values control.

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

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

The description identifies the resource as shared settings and implies mutation via 'change one only when the user asks,' but it never states a clear verb such as get or update. It explains several setting keys, yet an agent still has to infer the core read/write behavior from the schema and annotations.

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 phrase 'change one only when the user asks' gives a real usage constraint, which is more than none. However, it does not say when to read versus write settings, nor does it name an alternative tool such as ui_context or any sibling for related configuration.

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, so the safety bar is low. The description usefully discloses the output format (a page-opening link or an sfplan: line), but says nothing about whether the link encodes notes/layout/world state, whether it is stable or signed, or what the tool returns.

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

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

It is a single tight sentence fragment with no padding, but it is under-specified rather than concise: 'the page' has no referent and no front-loaded statement of what the tool returns.

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 seven parameters, no output schema, and a link-generation behavior whose content varies by flags, the description should explain what the emitted link/line actually encodes. It gives only the shape of the output, leaving the per-flag effects and return value entirely to inference.

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

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

Schema coverage is 71%, and 'save' and 'world' are undocumented in both schema and description. The description adds zero parameter meaning — nothing about how include_world, layout, notes, or as_of change the generated link, which is exactly the context a caller needs to pick flags.

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 conveys that the tool produces a shareable representation of a saved plan in two forms — a link that opens a copy on the page, or an 'sfplan:' line. It never states a verb or that it generates/returns these artifacts, and it doesn't distinguish itself from the obvious counterpart import_plan, which is what consumes such links.

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

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

There is no guidance on when to call this instead of siblings like import_plan, plans, plan_layout, or plan_from_factory. The reader must infer from the name alone that this is the export side of a share/import pair.

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 readOnlyHint=false with idempotentHint=true, and the description is consistent with a side-effecting-but-idempotent call: pin=true pins the place for the page, which explains the non-read-only hint. It also adds real behavioral context the annotations cannot convey, e.g. that a wrong token still opens the right place, that resource: centres on every node with overlays, and that the public map shows an unbuilt vanilla world.

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 key distinction (local vs public map) is front-loaded in the first clause, and the follow-up sentences cover the token grammar and pinning in a compact way. The parenthetical asides and line breaks make it denser than ideal, but 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 an 8-parameter tool with no output schema, the description explains what the links are but not the shape of the response, and several parameters (save, zoom, world) go unmentioned. The core invocation path via 'at' is well covered, so it is adequate but not complete.

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

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

Schema coverage is 63%, so the description must add some value and it does for 'at' (token grammar), 'pin' (pins as pin:N), and 'mode' (base map). However save, zoom, world, and as_of are left to the schema, and 'world' in particular is undocumented in both places despite being ambiguous next to the local/public map distinction. Baseline 3 for partial coverage is appropriate.

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

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

The description opens with a concrete verb and resource: it produces map links centred on a place, and immediately distinguishes the two link targets (this project's map, which draws your save, versus the public vanilla map). That is far more specific than a name restatement. It does not explicitly name a sibling such as factory_map or describe_location to differentiate itself, which keeps it from a 5.

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

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

Usage is implied rather than stated: the agent can infer this is the tool for 'show me this thing on a map', and the resource:<name> and pin=true clauses hint at intended scenarios. There is no explicit when-to-use/when-not guidance and no comparison against the many sibling tools that also deal with locations (describe_location, whereami, factory_map).

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

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

Beyond the destructiveHint annotation, the description explains that this records metadata rather than re-solving, that the siting survives save_as, and that downstream tools read it. The schema adds specifics about clear and preview, but the description itself provides strong behavioral context for a mutation 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 core purpose is front-loaded in the first sentence, and subsequent sentences explain non-obvious behavior. The prose is dense and uses domain-specific terms like recalls and on-pad census, but it is appropriately sized for a 10-parameter mutation tool.

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

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

For a complex mutation tool with no output schema, the description covers the key conceptual model, side effects, persistence behavior, and downstream consumers. It leaves some parameter details and return behavior to the schema, but the overall context is sufficiently complete.

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

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

Schema coverage is high, and the description adds meaningful semantics beyond the schema for the key spatial parameters: origin is the footprint centre in metres, yaw is about world Z, and footprint defaults to plan_layout's square for the largest floor. It does not clarify every parameter, such as save or world, but it adds real value where it matters most.

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 gives a specific verb set (record, update, clear) and resource (where a saved plan stands), with the exact fields affected (origin, yaw, footprint). It also clarifies that nothing is re-solved, which sharply distinguishes this from solve/layout editing tools.

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

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

The description gives clear usage context: a siting is a record, not a constraint; re-solving ignores it; save_as preserves it; and downstream tools such as recalls, diff_vs_save, and show_on_map consume it. It does not explicitly name when to choose this over edit_plan or plan_layout, but the intended 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 read-only, idempotent, non-destructive, closed-world, so the description needn't restate safety. It instead contributes real behavior: direction is inferred from connector roles or machine nature, ambiguous edges are walked both ways so results may over-report but never miss, and belts/pipes are traversed rather than listed. The only shortfall is that result shape (per-node fields, truncation behavior) is only partially implied by the 'note' sentence.

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 sentence before the sibling comparison and caveats, and there is no filler. The closing sentences are compressed to the point of being cryptic ('the runs crossed by the chain:/pipe: ids'), 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?

With 6 parameters, no output schema, and a traversal that can over-report, the description does well on direction semantics, the over-report caveat, and the conduit-id note. But it never says how `limit` truncates a walk or what `save`/`world` scope to, which matter for calling a graph walk correctly.

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

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

Schema coverage is 50%: `seed` and `as_of` are documented, and `direction` is documented in the schema while the description adds real meaning about how direction is inferred. However `save`, `world`, and `limit` are undocumented in both places, and the description never explains what the limit cap does to a traversal. Adequate but leaves the 3 dark parameters unaddressed.

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 states a specific action-resource pair: traverse the save's connection graph from a seed to find what feeds a machine/factory/building, or what it feeds. It also explicitly distinguishes itself from the sibling `factory_query show=links` (named-factory pairs vs. a single-seed walk), so an agent can pick correctly. The phrasing ('walked on the save's connections') is slightly dense but the scope is unambiguous.

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

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

It names the alternative (factory_query show=links for queries between named factories) and the condition that selects this tool instead (walking from one seed). It adds a concrete motivating scenario ('which feed can be repiped without dropping the generators behind it') and points to search_conduits for the conduit ids the note prints.

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

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

The description discloses important side effects beyond the annotations: listed asks are marked seen on the page, answered= records an answer, and dismissed= hides an advisory only when the user asks. This is consistent with readOnlyHint=false and useful for an agent to know before invoking the tool, though it does not discuss permissions or response format.

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

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

The description is dense but front-loaded with the critical 'call first' condition and then packs the returned context and side-effect guidance into a compact paragraph. It is appropriately sized for a complex context tool, though the run-on enumeration could be easier to scan.

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 does the necessary work of enumerating what the tool returns: view, plan/version, tab/selection, save consistency, queued asks, advisories, and recent external changes. It also covers triggers and side effects, leaving only the save/world parameters insufficiently explained.

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

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

Schema coverage is 50%, and the description adds useful meaning for answered= and dismissed= beyond the schema descriptions. However, the save and world parameters are undocumented in both schema and description, so the description only partially compensates for the coverage gap.

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

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

The description clearly identifies this as a page-context retrieval tool: it states 'What the web page has open' and enumerates the page view, plan/version, tab/selection, queued asks, advisories, and recent changes. The purpose is specific, though it does not explicitly differentiate itself from the many sibling 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 a strong trigger condition: 'call first when the user says "this", "here" or quotes an ask: or pin: id.' It also constrains side-effecting parameters with 'pass answered= once answered' and 'dismissed= hides an advisory, only when the user asks.' It does not name alternatives or when-not-to-use cases.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so safety is settled. The description contributes one genuinely useful behavioral fact — that results are filtered to alternates unless only_alternates=false — but says nothing about ordering, total counts, or how offset interacts with limit.

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

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

Two short clauses, no filler, with the scope stated first. Minor noise in the truncated 'Paged by offset=.' phrasing, which reads like a fragment rather than a sentence.

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

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

Six optional parameters, low schema coverage, and no output schema: the description should clarify world/save/as_of scoping and the limit cap of 25. Instead it covers only two of six parameters, leaving an agent likely to guess at world selection semantics.

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

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

Schema description coverage is only 17%, so the description must carry more of the burden. It explains only_alternates and offset, but leaves world, save, as_of, and limit undocumented — most importantly the save vs. as_of relationship and how 'this world' is actually selected.

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

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

Names the resource precisely (recipes unlocked in a given world) and states the alternates-only default, which meaningfully narrows what this returns. It does not name or contrast with close siblings such as search_recipes or alternates_for_item, 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?

There is no explicit when-to-use guidance and no named alternatives, even though search_recipes, recipe_detail, alternates_for_item, and rank_unlocks occupy adjacent territory. Usage is only implied by the phrase 'this world has unlocked'.

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 and closed-world, so the safety bar is low. The description adds genuinely useful context beyond annotations: the position comes from the save and may be minutes stale if it is an autosave, which is exactly the kind of caveat an agent needs before trusting coordinates.

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

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

Two short sentences, front-loaded with the core purpose, followed by the staleness caveat and the selector hint. Nothing is padded, though the opening line mixes purpose and return contents in a way that is slightly dense.