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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: each option is evaluated for and against across multiple objectives and deltas are reported per objective and never collapsed. It also clarifies that the printed baseline is the same quantity plan_factory reports. It stops short of stating safety/mutation status or cost, but the computational and reporting behavior is unusually well disclosed.

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

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

Front-loaded with the core action, then rationale and a semantics note. The 'recipe can be worthless for power yet excellent for parts' line earns its place by justifying the multi-objective design, though the jargon ('counterfactual LP') and the wording of the sources paragraph are slightly dense.

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 tool with no annotations and no output schema, the description helpfully characterizes the returned deltas but leaves most parameters and all behavioral/safety context undocumented. Adequate to understand intent, incomplete for confident invocation.

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

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

Schema coverage is only 20% (as_of is the sole documented parameter), so the description must compensate. It does add real meaning for `sources` (it is plan_factory's selector list and yields the same baseline), but `save`, `world`, and `hard_drive_id` are left unexplained, so it covers at best a fraction of the 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 and resource: 'Rank one pending drive's options by marginal value, via counterfactual LP.' An agent can immediately distinguish this advising/ranking tool from the similarly-named sibling list_pending_hard_drive_choices, which enumerates rather than ranks.

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 by the domain ('one pending drive') and the plan_factory comparison; there is no explicit statement of when to call this versus list_pending_hard_drive_choices or plan_factory, nor any prerequisite conditions. The plan_factory reference explains semantics rather than routing the agent between 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?

With no annotations, the description carries the full burden and does disclose useful output behavior: rows are marked HAVE or LOCKED and LOCKED rows name the granting schematic, with hard-drive vs milestone distinguished. It does not say whether 'save' is required for LOCKED data, what happens when no save is provided, or how 'world' interacts with 'save'.

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

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

Two tight sentences with no filler, and the core behavior (alternates first) is front-loaded. The second sentence is somewhat clipped but earns its place by explaining the HAVE/LOCKED output.

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, no-annotation, no-output-schema tool, the description covers the return semantics well but leaves 'world', the relationship between 'world' and 'save', and the acceptable format for 'save' unaddressed. Adequate but with clear gaps.

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

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

Schema coverage is only 20% (only 'as_of' is documented), so the description must compensate. It partially does: 'item' is the thing produced, 'save' governs HAVE/LOCKED marking, and 'include_locked' is implied by LOCKED rows. The 'world' parameter is never explained, leaving a real 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 states a specific resource and scope: 'every automatable recipe that makes an item, alternates first.' An agent can infer it returns recipe options for a given item, distinct from recipe_detail or search_recipes. It lacks a crisp verb and never names the sibling it is differentiated from, so it stops short of 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?

No when-to-use, when-not, or alternative is stated. The description never mentions compare_recipe_options, recipe_detail, or search_recipes, so the agent must guess which sibling to call for a recipe-listing need. Only implicit context ('alternates first') hints at use.

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

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

With no annotations, the description carries the full burden and does much of it: it discloses operation ordering (add, then drop, then prune_missing), that unnamed anchors are left untouched even if their ids are gone, that dropping the last machine is refused, and what prune_missing clears. It stops short of stating whether the change is destructive/reversible, whether it needs write permissions, or what the result 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 leads in the first sentence, followed by the rationale and the operation-ordering rules. Dense and mostly earned, though the second sentence's framing of the name_factory problem is slightly verbose for the information it delivers.

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 mutation tool with no annotations and no output schema, the description covers the central mechanics well but leaves several parameters (name, world, notes, dry_run, save) and the return/error surface unexplained. Adequate, with visible gaps.

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

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

Schema coverage is only 44% across 9 parameters. The description explains the add/drop grammar, the machine:<instance> form, and prune_missing behavior, and implies the save semantics ('ids this save no longer has'), but name, world, notes, and dry_run receive no explanation in either the description or 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: add or drop individual machines on a label without re-anchoring the rest. It explicitly contrasts with name_factory (re-anchors) and forget_factory (deletes the label), so an agent can place it within the sibling set without opening schemas.

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

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

Names the alternative name_factory and the condition that selects this tool instead (fixing one wrongly-included machine rather than re-selecting the whole factory), and routes label deletion to forget_factory. Both 'when to use' and 'when not to use' are covered.

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

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

With no annotations the description carries the full burden, and it does disclose genuinely non-obvious behavior: the result is solved by an LP rather than recipe-tree expansion (because of a real 2-cycle), and each row names the recipe chosen. However it never states whether the call is read-only or has side effects, and the 'save'/'world' state behavior is left unexplained.

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 meaning, and the parenthetical about the recycled-material 2-cycle earns its place by justifying why an LP is used instead of tree expansion. Slightly dense but no filler sentences.

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

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

For an 11-parameter, solver-backed tool with no annotations and no output schema, the description leaves too much unsaid: most parameters, the meaning of save/world/as_of state, and the shape of the returned rows are never covered.

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 and largely does not. It usefully defines qty as a rate per minute, but item, save, world, outlets, allow_sinks, offset, only_recipes and exclude_recipes get no explanation anywhere.

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

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

The description states a specific verb and resource: it produces a flattened bill of materials giving total raw and intermediate rates per qty/min of an item. That is concrete enough to distinguish it from recipe_detail or trace_upstream, though it does not name any sibling 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The reader can infer it is for totaling resource requirements, but nothing routes the agent between this and recipe_detail, trace_upstream, or alternates_for_item.

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

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

With no annotations the description carries the full burden, and it does disclose real behavior: the two data sources, that the save's destroyed-actor list *is* the collected list, that 'remaining' is a subtraction, and the important never_streamed caveat. It stops short of stating read-only status explicitly or any permission/rate context.

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

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

Front-loaded summary followed by a well-structured explanation of the two sources and the view modes using bullets. Most sentences carry information; the source/never_streamed prose is slightly long but each part earns its place for a tool this nuanced.

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, annotation-free tool with no output schema, the description supplies the hard part: the conceptual model of where counts come from and what the views return. It is still incomplete on several parameters (save, world, offset) and does not indicate result shape for census.

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 schema documents most parameters. The description adds meaning for 'show' (what each view returns), 'near' (origin defaulting to the player) and 'as_of' (pinning a world state), but leaves 'save', 'world' and 'offset' entirely unexplained in both description and 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 opening line states a specific verb+resource and scope: a census of map collectibles covering slugs, somersloops, Mercer spheres, mushrooms and drop pods. It is clearly readable as 'count/list collectibles in the world'. It never differentiates itself from closely related siblings such as somersloops and power_shards, 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 explains each view (census/collected/remaining/nearest) and when 'near' applies, which implies usage. However it never names an alternative tool or an explicit when-not-to-use condition, so the choice between this and the somersloops/power_shards siblings is left to inference.

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

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

With no annotations, the description carries the full burden and provides strong behavioral context: the hard power constraint, the consequence of exceeding it (fuse blows and grid shuts down until manually reset), and the fact that generators are free to energise and refund power for later waves. It does not, however, disclose side effects of the save parameter, authentication needs, or return behavior.

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

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

The description is front-loaded with the core purpose and then unfolds the startup constraint and generator behavior in a logical sequence. It is somewhat long but the domain context is relevant, and no sentence feels purely redundant for such a specialised planning 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 21-parameter tool with low schema description coverage and no output schema, the description does not provide enough invocation detail. It explains the conceptual model well but leaves most arguments and the expected return shape undocumented.

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

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

The schema has 21 parameters with only 19% description coverage, and the description adds little: it mentions only plan= and that the tool takes plan_factory's arguments. Parameters such as save, world, clocks, objective, allow_sinks, headroom_mw, machine_cost_mw, and many recipe filters are not explained in 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?

The opening line states a specific action and resource: determining the startup switch-on order for a built plant. It explicitly contrasts this with a build order and notes that it does not say what to build first, so an agent can distinguish it from planning tools like plan_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?

The description gives clear context for when to use it: after construction, for startup energisation, not for deciding what to build. It also points to plan_factory arguments and the plan= recall option, but it does not explicitly exclude or compare against other sibling tools such as site_plan or plan_layout.

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

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

No annotations are present, so the description carries the full burden. It usefully discloses the computation mechanism ('solved end to end with the LP') and the result dimensions (raw resource per unit, whole buildings, net power, byproducts needing an outlet), but says nothing about read-only nature, permissions, or cost of invocation for a 9-parameter analysis call.

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

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

Front-loaded with the core purpose, then the differentiation, then the mechanics. The illustrative route example earns its space by making the LP comparison concrete. Two sentences plus example, little waste.

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

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

With no output schema, the description appropriately explains what the comparison returns (pricing dimensions), which is a genuine plus. However, for a 9-parameter tool with 22% schema coverage and no annotations, seven undocumented parameters leave the definition materially incomplete for correct invocation.

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

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

Schema description coverage is only 22% (2 of 9 params documented in-schema), so the description must compensate and largely does not. It only loosely hints at 'outlets' via 'byproducts needing an outlet'; rate, save, world, allow_sinks, and per_resource receive no explanation in either place.

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 what each actually costs') and explicitly distinguishes itself from the sibling 'alternates_for_item'. The added contrast with a naive recipe list leaves no ambiguity about what this tool computes.

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

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

Gives an explicit when-not ('Not a recipe list -- alternates_for_item already does that') and routes the agent to the correct sibling for that case. It stops short of distinguishing from other planning siblings like plan_factory or propose_factories, so it is clear context without full alternatives coverage.

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

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

With no annotations, the description carries the burden and does it well: it explains that both crate types are recoverable, are not spendable stock, and self-delete when emptied, and warns that a spent crate depends on someone walking back. It omits read-only/pagination behavior, but the domain semantics disclosed are substantive and non-obvious.

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

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

Front-loaded with the core purpose, then incremental caveats in three tight sentences with no filler. Slightly prose-heavy, but every 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?

For a 5-parameter read tool with no output schema and no annotations, the description covers the crates' semantics but omits parameter behavior, pagination, and what the rows look like. Adequate on domain meaning, incomplete on invocation detail.

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 40% (as_of and limit are documented; save, world, and offset are not), so the description needs to compensate and it does not mention parameters at all. An agent gets no guidance on how save, world, or offset scope the results, leaving half the parameters undocumented 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 first sentence states a concrete verb and resource: it reports what is in each ground crate and where to walk to reach it. It also distinguishes two subtypes (death crate vs dismantle crate) that an agent would otherwise conflate. It does not name a sibling (e.g. stock/storage) to sharpen the boundary, 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?

Usage is implied rather than stated: the warning that crates are 'NEITHER spendable stock' implicitly contrasts this tool with the stock/storage tools. There is no explicit when-to-call, when-not-to-call, or named alternative, so an agent must infer the trigger.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it states that off-map points return 'off-map or ocean' rather than a guessed region, explains that elevation is never averaged across two methods, describes the terrain_m texel read with layer/accuracy/water details, distinguishes ground vs built elevation for nodes vs foundations, explains that conduits are measured against drawn lines not corner points, and notes that a zero count means true absence with a readable save.

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

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

The description is front-loaded with the core purpose and organized logically from input formats to behavior to a sibling note. It is somewhat long and contains a few dense, stylized phrases, but for a tool with five parameters, no annotations, and no output schema, most sentences add useful context rather than 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?

Given high complexity, no annotations, and no output schema, the description covers return behavior extensively—region, elevation modes, conduit counting, and absence semantics. It leaves `save`, `world`, and `as_of` largely unexplained, which is a meaningful gap for a tool that supports pinning to earlier world states, but the overall behavioral picture is strong.

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

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

Schema coverage is 60%, and the description meaningfully extends the `at` parameter beyond the schema by specifying that it accepts 'x,y' in metres, `me`, a named factory, `slab:<n>` from `factory_map show=slabs`, or a `chain:`/`pipe:` run from `search_conduits`. It does not expand on `save`, `world`, `as_of`, or `radius_m`, 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?

The first sentence states a specific verb and three resources: name the region, sample elevation, count conduits. It later distinguishes this tool from `search_conduits` (which lists runs) and from `factory_map` (source of slab ids), so an agent can tell what makes this tool unique.

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

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

The description implies when to use the tool by describing what it returns, and it notes that `search_conduits` lists the runs themselves, but it never explicitly states when to choose this tool over alternatives like `whereami`, `show_on_map`, or `list_regions`. Usage is inferable, not spelled out.

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

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

With no annotations, the description carries the full burden and discharges it richly: identity-based matching rules, action ordering (UNPAUSE then SETRECIPE then BUILD), incremental power accounting, RANGE vs number for unidentifiable machines, the built-vs-energised asymmetry, non-persisted grid membership, and read-only saves with no dismantle action. This is exactly the kind of behavioral disclosure an agent needs.

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

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

It is long, but the length is largely earned given the tool's conceptual complexity, and the first sentence leads with purpose. Paragraphing separates related concerns, though several sentences are dense enough that a skimming agent could lose the thread.

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 and no annotations, yet the description explains the return shape well: plan-id hashing, stage-grouped diffs, RANGE answers, and provenance of sa: tokens. It is strong on concept but leaves many of the 20 parameters unexplained, which leaves the invocation surface 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 25% across 20 parameters, so the description must compensate. It explains plan=, stage=, and factory= in prose and notes save handling, but leaves the majority of parameters (clocks, exports, sources, objective, show_cost, allow_sinks, target_item, recipe filters, machine_cost_mw, only_free_nodes, extractor_clocks, limit, world) unaddressed, so it only partially fills the 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 line states a specific purpose: computing what to change to turn the current factory into the one plan_factory plans. It distinguishes itself conceptually from plan_factory (it re-solves using that tool's arguments) and from commission_plan (whose stage partition it reuses), but the verb 'diff' is never stated plainly and the purpose is embedded in dense prose rather than front-loaded as a one-line statement.

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

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

It gives concrete usage cues: recall a stored plan with plan=, narrow with stage=<n>, use stage=0 for an overview without a stored plan. However it never frames when to reach for this tool versus plan_factory or commission_plan, and gives no exclusions or prerequisites beyond the read-only note.

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

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

With no annotations, the description carries the full burden and delivers unusual depth: it explains that every item balance is an equality, that an unconsumeable byproduct makes the plan INFEASIBLE rather than being ignored, and that sinks apply to solids only since fluids must be consumed or packaged. It omits return format, pagination, and auth/cost behavior, so it is strong but not exhaustive.

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

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

Front-loads the core purpose, then explains the domain mechanics and the `item` scoping option in three compact paragraphs. Every sentence adds meaning with little filler, though the middle paragraph is dense.

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 annotations, no output schema, and 17% schema coverage, the description explains the domain semantics well but leaves the bulk of the parameters undocumented and never describes the response shape. An agent knows why to call it but not how to configure most of its inputs.

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% of 12 parameters, so the description must compensate, yet it only clarifies the `item` parameter. The other ten parameters (save, world, exports, sources, objective, allow_sinks, target_item, exclude_recipes, export_minimums) are left with bare titles and no semantic explanation in either schema or description.

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

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

States a specific verb and resource ('Explain which byproducts stall a plan, and what can legally consume them') and describes the exact output focus (which item is stuck, sinkability, absorbing recipes). It does not name or contrast any sibling tool, but the purpose is distinctive enough to distinguish it from the surrounding factory/plan 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 states the scoping option ('Pass item to focus on one byproduct instead of the whole plan') and implicitly the use case (diagnosing infeasibility). However, there is no explicit when-to-use guidance, no prerequisites, and no comparison to alternatives such as factory_health or trace_upstream.

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

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

With no annotations, the description carries the burden well: it discloses that floors are inferred from geometry, that no storey pitch is assumed, the threshold for marking a band 'minor' (under a quarter of the largest deck), that minors are reported rather than merged, and the default sort order. It omits whether this is strictly a read operation and how errors or ambiguous platforms are surfaced.

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

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

The answer is front-loaded in the first sentence and the remaining prose all adds derivational context. It is somewhat wordy across three paragraphs 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?

For a 7-parameter, no-output-schema, unannotated tool, the description covers the return shape (row per platform, or floor-by-floor), default ordering, and the core derivation rules. Remaining gaps are the unqualified save/world/as_of parameters and read-only confirmation.

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%. The description meaningfully augments platform= by noting the index is stable across calls on one save and explains the world-vs-narrowed behavior, but save, world, as_of, limit, and offset receive no added semantic detail beyond their schema hints.

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 resource and outcome: how many decks a factory has and what stands on each. It is clearly not a layout or map tool, and the geometry-derivation detail makes the scope concrete. It stops short of naming the closest siblings (factory_map, factory_query, factory_health) to draw an explicit 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?

It gives clear operational context: whole-world by default with one row per platform, narrowable via platform= or factory=, and that a single-platform query switches to a floor-by-floor answer. There is no explicit when-not guidance or routing to an alternative tool, 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?

With no annotations, the description carries the full behavioral burden and does so richly: it enumerates the state taxonomy worst-first, defines the `cause` semantics, explains that blocked/dead node/no recipe/starved/stalled feed the `todo` count, and describes how `offset` pages every table at once. It also discloses a genuine data limitation (the save records no 'has power' flag, so the wire is the only electrical fact) and that fluid diagnosis follows a fixed ladder. This is unusually complete behavioral disclosure.

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 purpose sentence is correctly front-loaded, but the body is dense, jargon-heavy prose with long dependent clauses ('A stalled machine no generator can reach over the wires says so in its `cause`…') that is hard to parse quickly. Most content relates to real behavior, but the length-to-clarity ratio is poor for an agent scanning for a decision.

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 diagnostic with no output schema, no annotations, and only 50% schema coverage, the description does describe the returned shape (per-machine states and causes, the sweep's `todo` column, world-wide plumbing faults). It is nearly complete, with the only real gap being the unexplained `save` and `world` inputs.

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 50%, so the description must compensate for undocumented params. It does explain `offset` meaningfully ('pages every table in the answer at once, worst first'), which the schema leaves bare, and it implies the sweep semantics behind `factory`='all'. However, `save` and `world` receive no explanation, and `as_of`/`limit` are already covered by the schema. Partial compensation lands at the baseline 3.

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 specific thing measured (uptime per machine) and the diagnostic question it answers (why each stopped machine stopped), which is a clear verb+resource for an inspection tool. It also scopes itself against the sibling `trace_upstream` ('walks the rest'), so an agent can tell where this tool ends. It does not explicitly differentiate itself from adjacent reporting siblings such as `power_report` or `factory_query`, which keeps it 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?

Usage context is clear: reach for this to find why machines stopped, and use `trace_upstream` to walk beyond the one hop this tool provides. It also explains that the world-wide sweep surfaces three plumbing faults not scoped to a factory. There is no explicit when-NOT-to-use statement or comparison to `power_report`/`factory_query`, so no exclusions are drawn.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavior: three signals are reported rather than one merged answer, each with known failure modes (476-machine blob, shattered fragments, no coverage of ground-built parts). It also states that show=slabs includes bare platforms with tile count, extent, bbox and elevation, and that small pads are collapsed to one line – useful return-shape context.

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

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

Purpose is front-loaded, which is correct, but the second sentence is a long unpacked clause chain ('because none is right alone: … blob; … fragments; … slab') that costs the reader effort for the information delivered. The show=slabs paragraph earns its place; the signal-disagreement sentence is bloated relative to its content.

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

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

With no output schema and no annotations, the description has to describe both behavior and returns, and it partly does: the three-signal model, the slabs listing detail, and the bare-platform fields. It leaves the `save`/`world`/`offset` parameters and the overall response shape of the candidates/named modes unexplained, so it is solid but not fully complete for a 6-parameter tool.

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

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

Schema coverage is 50%, with `show` and `as_of`/`limit` already documented in the schema. The description expands meaning for `show=slabs` beyond the bare enum list, which is real added value, but says nothing about `save`, `world`, or `offset`, leaving half of the parameter surface to the schema alone. Baseline 3 is appropriate.

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

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

The first sentence names a specific resource – proposed factories – and the mechanism (power islands and belt topology) plus the naming overlay, which is more than a restatement of the name. It implicitly separates this from list_factories/propose_factories, but never names a sibling outright, so an agent must 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?

It gives one actionable route – when the three signals disagree, use `name_factory` with a product:/near:/slab: selector – which is genuine usage guidance. However, it never says when to reach for factory_map rather than factory_query, factory_sites, or list_factories, all of which sit adjacent in the sibling set.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explains the crucial NAMEPLATE vs MEASURED distinction, notes that idle machines measure 0 and are not broken, and warns that machines without monitors are excluded from measured to avoid inventing output. These are deep, non-obvious behavioral traits that an agent cannot infer from the schema.

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

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

The description is front-loaded with the purpose, then organized into a bulleted list of show aspects followed by a measurement-semantics paragraph. It is dense and long, but each section earns its place by explaining how to interpret the returned data; there is little redundant 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?

Given 8 parameters, no output schema, and moderate schema coverage, the description is largely complete for the main query workflow: it explains show aspects, pagination behavior, and rate semantics. It leaves save, world, and limit without description-level context, and does not say how to obtain a factory selector, but the central calling pattern is fully covered.

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 63%, so the description must add meaning beyond the schema, and it does: it expands on what each show aspect returns (e.g., 'balance -- per-item produced vs consumed vs net -- the sign is the point', 'internal -- made and eaten inside the set'), clarifies that multiple show values are accepted, and explains that offset pages all tables together. It does not cover save, world, or limit semantics, but the core query parameters are well served.

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: 'Ask one thing about one factory: what it makes, needs, draws, or touches.' This clearly distinguishes a single-factory detail query from list-oriented siblings like list_factories. However, it stops short of explicitly naming alternative tools such as factory_health or factory_map for sibling differentiation.

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

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

The description gives concrete when-to-use guidance for aspects and pagination: 'offset pages every table in the answer at once, so asking for one aspect at a time is what you want when a factory has more machines than fit.' It does not explicitly compare the tool to siblings or state exclusions, but the context for selecting show combinations 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?

No annotations are supplied, so the description carries the full disclosure burden. It reveals only two traits: results are ordered largest-first and only 'built' buildings are counted. It is silent on authentication/save requirements, pagination behavior, reversibility, and what the grouping actually yields, which is thin for a five-parameter read 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?

It is a single short sentence, but its brevity is under-specification rather than efficient conciseness; it conveys almost no actionable information and there is no front-loaded verb or scope. The brevity does not earn its place because it omits everything an agent needs.

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

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

With no annotations, no output schema, and five parameters at 40% coverage, the description would need to explain inputs, result shape, and applicability. Instead it offers one fragment, leaving the save/world scoping and pagination contract entirely 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 description coverage is only 40% (as_of and limit are documented; save, world, offset are not), so the description is expected to compensate and does not mention a single parameter. Nothing explains what 'save' or 'world' select or how limit/offset paginate, leaving the majority of parameters 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 describes the returned resource ('built production buildings clustered into sites, largest first') but supplies no verb and no scope, so it reads more like a return-value summary than a statement of what the tool does. It is not clearly distinguished from close siblings such as rank_build_sites, factory_map, or list_buildings, so an agent cannot tell which of these to pick from the text 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?

There is no when-to-use guidance, no mention of prerequisites (whether a save or world must be specified), and no routing to alternatives like rank_build_sites or factory_map. The only hint at behavior is the implicit 'largest first' ordering, which is not framed as selection criteria.

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

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

With no annotations, the description carries the full burden, and it does disclose one important trait: the machines are not affected, so this is a label-only mutation. It says nothing about reversibility, whether the factory must be empty, or how the save/world/as_of parameters change 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, with the destructive scope clarification front-loaded. No filler to trim.

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

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

For a mutation tool with no annotations, no output schema, and three undocumented parameters, the description is too thin. The save/world/as_of semantics that likely govern what state gets mutated are unexplained, so an agent cannot call this correctly with confidence.

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 25% (just `as_of`), and the description explains none of the four parameters. The meaning of `save` and `world` — which look like world-state selection inputs — is left entirely to guesswork.

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 ('delete a factory label') and immediately scopes it ('machines themselves are untouched'), which distinguishes it from a teardown-style operation and from siblings like name_factory/rename_factory. It does not explicitly name a sibling alternative, but the resource 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?

There is no statement of when to use this versus alternatives such as forget_plan or rename_factory, and no prerequisites or preconditions are given. Usage is only implied by the verb 'delete'.

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

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

With no annotations, the description carries the full burden and does well: it discloses the operation is destructive ("Delete"), scopes the blast radius ("Nothing in the world is touched"), and discloses recoverability ("plan_log can undo it"). It stops short of covering failure cases such as a non-existent plan name.

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, front-loaded sentences with zero filler; the verb and scope lead, and the reversibility note follows efficiently.

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 delete with no output schema, the scope and reversibility disclosure is adequate, but the presence of four optional parameters with only 40% schema coverage means the description leaves meaningful invocation gaps unaddressed.

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 40%, so the description must compensate and does not. The optional save, world, and base_rev parameters are undocumented in both places, and the description never explains that name identifies the plan or how as_of/base_rev affect the delete.

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 ("Delete a saved plan") that is immediately distinguishable from siblings like rename_plan, list_plans, and plan_log. However, it does not explicitly name the contrasting sibling or spell out the saved-plan vs. world-state distinction as a routing rule, keeping it just 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?

Usage context is implied rather than stated: mentioning that plan_log can undo it hints at recovery flow, but there is no explicit when-to-use or when-not-to-use guidance versus rename_plan or forgetting a factory. The agent must infer the intent.

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

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

With no annotations, the description carries the full behavioral burden and does a fair job: it discloses the HAVE/LOCKED save-relative marking, the hard framing of paging (envelope reports remaining count and offset), and the practical scale problem (539 rows, ~60k chars). It does not cover auth, mutation risk, or what the rows themselves contain, but the paging and save-coupling disclosure is genuinely beyond schema.

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

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

Front-loads the kind list well, but the middle paragraph editorializes ('the worst failure mode a planner has', 'not an answer, it is a context eviction') at the cost of density. The justification for locked-state awareness is valuable, but it is delivered with more words than needed.

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 parameters, no annotations, no output schema, and 57% schema coverage. The description covers paging and the locked/have semantic but leaves the save/as_of/world pinning parameters and the deprecated kind alias unexplained, so an agent must infer how to pin a world state or query a specific save.

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%. The description enumerates the building_kind values and explains the paging parameters conceptually (envelope/offset), which partially compensates, but it never mentions save, as_of, world, or the retired 'kind' parameter that the schema flags as superseded.

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 resource and enumeration of the kind values, so an agent knows this lists building definitions filtered by category. It is distinguishable from siblings like search_items or recipe_detail, though the verb is implicit in the noun phrase 'Buildings by kind' rather than stated outright.

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 supplies useful context for when the HAVE/LOCKED marking matters (logistics tier assumptions) and explains the paging model, but it never states when to prefer this tool over siblings, nor any exclusions or prerequisites. Usage is implied rather than directed.

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?

No annotations are provided, so the description carries full disclosure burden, yet it only adds that each entry includes a "still standing" fraction. It says nothing about save/as_of pinning semantics, world selection, or what the listing returns, leaving the mutability/safety picture unstated.

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

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

One sentence, front-loaded, with no wasted words. However, the brevity comes at the cost of specification rather than being tight-but-complete.

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 annotations, no output schema, and three loosely documented parameters, the description is inadequate for correct invocation. It does not explain the save/as_of pinning model or defaults that determine which world state is listed.

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% (only as_of is documented as a sav: token), so the description must compensate for save and world. It mentions "this world" only obliquely, and never explains the save token or how save/world/as_of interact, so the parameter gap remains.

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

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

The verb is implicit ("Named factories for this world") and the resource (factories) is clear, but there is no differentiation from near siblings like factory_query, factory_map, or factory_health, which plausibly also enumerate factories. The agent can infer it is a listing tool, but the scope versus those siblings is ambiguous.

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 offers no when-to-use, when-not-to-use, or alternative routing despite many factory-related siblings. Nothing tells the agent whether this is the right entry point versus factory_query or factory_health.

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?

No annotations are provided, so the description carries full behavioral burden. It does not disclose read-only status, pagination behavior, side effects, or return format, leaving the agent to assume a safe read.

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

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

One terse sentence fragment, no wasted words, but its extreme brevity borders on under-specification.

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

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

For a tool with five parameters, no annotations, and no output schema, the description omits crucial usage and parameter context, leaving significant gaps.

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

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

Schema description coverage is 40% (only as_of and limit have descriptions). The description adds no meaning to any of the five parameters, failing to 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 is a noun phrase that restates the tool name, adding only 'with rerolls left' and 'stored in the save'. It does not state a verb or distinguish from the sibling tool advise_hard_drive_pick.

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 when-to-use guidance, prerequisites, or alternatives are provided. An 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?

With no annotations, the description carries the full burden. It discloses important behavioral traits: nothing is solved, the output shows stored arguments and saved siting rather than current resolution, and plan versions are exposed via `base_rev`. It does not explicitly state read-only safety, auth needs, or pagination behavior, 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?

The description is front-loaded with the list behavior, then the `name` mode, then version semantics. Each paragraph earns its place, though some cross-tool guidance about `base_rev` and `plan_log` is slightly ancillary for a list 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?

There is no output schema and no annotations, so the description must carry more context. It explains the main return semantics and the `name` mode well, but leaves `save` and `world` params, output ordering/shape, and read-only safety unaddressed. Adequate but with clear gaps.

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

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

Schema description coverage is 50%. The description adds meaning for `name` and indirectly for `as_of` by discussing world-state pinning and versions, but `save` and `world` are left undocumented in both schema and description. The added value is real but incomplete against the low coverage.

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

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

The description states a specific resource and scope: saved plans for this world, their versions, and whether the world has moved under them. It also distinguishes the `name` mode as returning one plan's stored request rather than resolving it, and contrasts the tool with `plan_factory`. An agent can tell this apart from siblings without opening the schema.

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

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

It explicitly names alternatives and conditions: use this to answer "what did I ask for" without spending an LP solve, use `plan_factory plan=<name>` for current resolution, and use `plan_log` for version history and undo. The `name` parameter's behavior is also tied to a clear usage condition.

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

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

With no annotations, the description carries the full burden and discharges it well: it discloses that names are advisory, that boundaries are downsampled to a 256 m grid to publish and 64 m to look up, that a boundary-adjacent name can be one cell out, and that `anchor` provably lies inside the region whereas a centroid may not. These are exactly the behavioral traits an agent needs to avoid misusing the 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 purpose, then two tightly scoped paragraphs that each add non-redundant value (advisory-boundary caveat, anchor-vs-centroid rationale). No filler sentences or restated titles.

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

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

For a two-parameter, read-only listing tool with no output schema and no annotations, the description covers the semantics and caveats of the returned data well. It could still say a little more about the shape of a region record beyond `anchor`, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 50% and the description compensates: it explains that `resource` restricts results to regions containing that resource, and effectively reinforces the schema's note that `with_resource` is retired in favor of `resource=`. The `anchor` discussion concerns output fields rather than inputs, so it does not leave an input parameter uninterpreted.

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 exactly what is returned (named map regions) and the optional filter (those containing a given resource), which is enough to distinguish it from siblings like whereami, describe_location, or search_resource_nodes. It is a noun phrase rather than a verb-led statement, but the resource and scope are 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 explicitly tells the agent when to use the results ('to talk about places, not to compute with') and points to the alternative for computation ('every node row also carries an exact grid cell'). It does not name which sibling to call instead when exact geometry is needed, so it falls short of full when/when-not/alternative routing.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It adds valuable context about unsupported files being reported separately and pre-1.0 saves being unparseable, which is beyond basic listing semantics. However, it does not mention return formatting or other edge cases.

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 extremely concise: two sentences, front-loaded with the primary action, and the second sentence adds a meaningful caveat without wasting words. Every sentence earns its place.

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

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

For a zero-parameter listing tool, the description covers purpose, sorting order, and error handling for unsupported files. It lacks explicit return structure details, but given the tool's simplicity and absent output schema, it is nearly complete.

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

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

The tool has zero parameters, so the baseline score is 4. There is nothing to add about parameter semantics; the description correctly focuses on behavior instead of documenting 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 clearly states the tool's function: 'List save games grouped by world, newest first.' This uses a specific verb and resource, and the grouping by world distinguishes it from sibling tools like list_factories.

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

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

The description implies usage for listing world save data but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions. It lacks direct sibling differentiation or conditional advice.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses meaningful internal behavior: MAM capabilities are distinct from recipes, production amplification is not directly recorded in the save and is derived from the purchased-schematic set, and capability rows are marked LOCKS to indicate tool-argument gating. It still does not state read-only safety, permissions, or return format, but the domain disclosure 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 first sentence front-loads the purpose effectively, but the following paragraphs drift into detailed save-file implementation lore such as BP_UnlockSubsystem_C and mIsBuildingOverclockUnlocked. That context is relevant to trust the LOCKS marker, yet it is longer and more technical than needed for most invocation decisions.

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

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

Given 9 parameters, no annotations, and no output schema, the description should explain more about invocation and expected results. It provides useful domain context but omits parameter usage, pagination behavior, and return shape, leaving the agent without guidance for several important call decisions.

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

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

The description adds no parameter-specific meaning beyond the schema. With 9 parameters and only 67% schema description coverage, several parameters (save, world, offset) lack documentation in either place, and the description does not compensate or explain how to use query, show, as_of, or retired parameters. The schema does some work, but the description contributes nothing to parameter semantics.

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

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

The description states a specific resource (MAM research) and the three questions it answers: what is left, what it costs, and what you can afford right now. It also distinguishes MAM capabilities from recipes, which helps separate it from recipe-oriented siblings. It does not explicitly name a sibling tool, 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?

Usage is implied by the opening question set and by the contrast between MAM capabilities and recipes. However, there is no explicit 'use this when' or 'do not use this when' guidance, and no named alternatives among the many sibling tools. The agent must infer the appropriate context.

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

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

With no annotations, the description carries the full burden, and it delivers a genuinely useful disclosure: READY reflects the bill, not access, and the access gate is not present in shipped data. That caveat prevents a real misinterpretation, though return format and pagination remain unstated.

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 first line is well front-loaded, but the remaining prose is analogy-heavy and cryptic ('SchematicLadder', 'spendable stock', 'in the same words'), which costs the agent effort without proportional payoff.

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

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

For a 10-parameter, no-annotation, no-output-schema tool, the description explains the concept and the key caveat but leaves the parameter set and result shape largely to the schema. Adequate but with clear gaps for a tool of this complexity.

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 70%, so the schema already documents most parameters (show, tier, as_of, limit, query, retired params). The description hints at the show=affordable semantics but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The opening line states the resource (HUB milestones) and the three things it returns: what's left, what each costs, and what you can afford now. It also distinguishes itself from siblings by explicitly framing itself as the same questions `mam_research` answers, applied to the other ladder. The purpose is clear despite the dense jargon.

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 implicitly routes the agent by noting that `phase_requirements` is where the elevator gate stands and that `mam_research` covers the parallel ladder, but it never states an explicit 'use this when' condition. Usage must be inferred from the analogies rather than being spelled out.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that membership is stored as stable instance ids surviving moves/autosave rotation, and warns that the same-name call is destructive to prior membership. It does not cover permissions, rate/latency, or what dry_run actually returns, which for a 9-param mutation tool is a real but smaller 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?

Three sentences, front-loaded with the core action, then persistence rationale, then the destructive re-anchor warning and sibling contrasts. No filler; every sentence carries distinct information.

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

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

For a 9-parameter, no-annotation, no-output-schema tool, the description covers the headline behavior and the destructive case well but omits dry_run, save/world scoping, and any hint of the return value (e.g. a label token). Adequate but with clear gaps.

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

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

Schema coverage is only 44%, so the description must compensate, and it partially does by explaining the semantics of `name` (a label over stable instance ids) and the re-anchor behavior tied to `select`. But it says nothing about save, world, notes, or dry_run, leaving nearly half the parameters documented in neither place.

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 (name) and resource (a set of machines) plus the persistence effect ('persist it for this world'). It explicitly distinguishes itself from the two nearest siblings, amend_factory and rename_factory, so an agent can route 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?

Names both alternatives and the condition that selects each: re-calling with the same name re-anchors and drops non-matching machines, amend_factory adds/drops a few, rename_factory changes only the name. That is explicit when-to-use/when-to-use-something-else guidance rather than 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?

With no annotations, the description carries the full burden, and it does disclose a genuine behavioral caveat: the per-phase item table is DEPRECATED and frozen, and is shown labelled rather than trusted. That is useful data-fidelity context. It still omits permissions, return shape, and error 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?

It is short and front-loads the subject before the deprecation caveat. The awkward line breaks and lore-flavored phrasing cost it a point, but there is little 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, no annotations, and three loosely documented parameters, the description should work harder. It leaves the return format, the meaning of save/world, and the tool's relationship to sibling phase/milestone tools 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 only 33% (only as_of is documented), and the description explains neither 'save' nor 'world', so it fails to compensate for the coverage gap. It does loosely gesture at the as_of concept ('pin to one world state') but that meaning already lives in the schema, adding nothing.

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 does identify a specific resource (Space Elevator phase requirements) and distinguishes live vs. deprecated records, which no sibling covers. However the verb is oblique ('what the Space Elevator still wants') and it never states cleanly that it returns per-phase item requirements. An agent can guess the domain but not the exact output.

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

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

There is no when-to-use or when-not-to-use guidance, and no sibling alternative is named despite many plausible overlaps (milestones, mam_research, unlocked_recipes). The only procedural hint is 'Read the header line first,' which concerns reading the output, not deciding to call the 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?

With no annotations, the description carries the full burden and does so well: it explains the LP balances items as equalities (making byproducts infeasible rather than vanishing), reports machine counts as exact clocked ratios, discloses that unknown export tokens are refused by name, describes the base_rev merge/conflict semantics on save, and clarifies that site_at measures water but never alters LP 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?

The length is largely justified for a 30-argument LP tool, and the purpose is front-loaded before the argument tour. Some asides ('Two things worth reading twice', the quadratic-vs-linear rationale) are informative rather than wasteful, but the block is dense enough that it could be tightened without losing meaning.

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

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

For a complex tool with 30 params, no annotations, and no output schema, the description covers usage, infeasibility behavior, save/merge semantics, and related tools thoroughly. The remaining gap is the handful of unexplained arguments, so it is strong but not fully complete.

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

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

Schema description coverage is only 53% across 30 params, and the prose compensates heavily by explaining sources selectors, clocks vs extractor_clocks, exports/MW token, sloops budget, objective, required, logistics_items, save_as/base_rev, and site_at. Still, several parameters (allow_sinks, only_free_nodes, only_recipes, exclude_recipes, export_minimums) receive no prose explanation at all.

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 verb and resource ('Optimise a factory with an LP over this world's unlocked recipes'), and the body explicitly distinguishes the tool from siblings like search_resource_nodes (for discovery), list_plans (naming saved plans), site_plan (setting siting), diff_vs_save, and show_on_map. An agent can tell what this does and what it does not do.

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

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

Extensive guidance on when to use which argument: extractor_clocks is 'the usual play' vs clocks being 'only for asking a different question', exports replaces rather than extends the default, sloops is a budget not a switch. It also routes to search_resource_nodes for finding ids and site_plan for repositioning. However it never explicitly states when to choose plan_factory over plan_layout/commission_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?

With no annotations, the description carries the full burden and does real work: it discloses the deliberate omissions (no world coordinates, no belt routing, because no terrain data) and explains the derivation rules (blocks split by throughput, floors follow chain depth with logistics decks between). It does not state whether the operation is read-only/side-effect-free or what cost/preconditions exist, so a 4 rather than 5.

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

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

Front-loaded with the core purpose, then the `show` modes, then the deliberate exclusions, then the derivation rationale. Sentences are dense but each earns its place. Slightly long, and the blocks/floors rationale paragraph could be trimmed, but structure is sound.

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 27-parameter tool with no annotations, no output schema and 48% schema coverage, the description covers purpose and output modes well but leaves more than half the parameters and the entire side-effect/precondition surface unexplained. The 'same as plan_factory' pointer helps but shifts burden onto the sibling's definition.

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 48% of 27 parameters are schema-documented, so the description must compensate. It richly explains `show` (the main control) and clarifies blocks/floors semantics, and defers the rest via 'Same arguments as plan_factory'. But many meaningful parameters (objective, allow_sinks, exports, sources, clocks, only_recipes, machine_cost_mw) get no explanation in either place, leaving the agent guessing.

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 concrete transformation (plan -> buildable schematic) and then enumerates the six output shapes via `show`. It explicitly positions itself against the sibling plan_factory ('Same arguments as plan_factory, plus show'), so the agent can distinguish it without opening either schema.

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

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

It tells the agent what the tool is for and names the alternative it extends (plan_factory), and it rules out a class of use cases ('schematic, not blueprint... no world coordinates or belt routing'), implicitly routing coordinate-level needs elsewhere. It does not give an explicit when-not-to-use clause or name the sibling that provides coordinates, so it stops short of 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?

With no annotations, the description carries the full burden and largely succeeds: it discloses that undo/restore are non-destructive (they write a NEW version), that both require base_rev and merge like any other edit, and that forgotten plans remain retrievable so a forget can be undone. It omits permissions/auth requirements and rate limits, but the core behavioral traits are well covered.

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 listing behavior is front-loaded in the first sentence, with the mutation semantics following as supporting detail. Every sentence conveys distinct information with no filler or redundancy.

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

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

Given 9 parameters, no annotations, and no output schema, the description is fairly complete: it describes the return ordering ('newest first'), the attribution ('who changed what'), and the mutation semantics. The main gaps are the undocumented save parameter and the lack of any note on how as_of/since interact with the returned rows.

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?

At 67% schema coverage, the schema already documents undo, restore, base_rev, as_of, limit, and since. The description meaningfully adds to the schema by clarifying that undo/restore create new versions rather than rewriting history and that they merge through the normal edit path. It leaves save and world undescribed in both places, so it 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 states a specific resource and scope: 'One plan's versions, newest first: who changed what, from chat or from the page.' This clearly sets it apart from the sibling list_plans, which lists plans rather than the version history of a single plan. However, it never names list_plans or diff_vs_save as the alternatives, so the differentiation is implicit rather than 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?

It gives good usage guidance for the mutation paths, explaining that undo=<v> and restore=<v> both require base_rev and merge like any other edit. But it offers no guidance on when to reach for plan_log versus list_plans, diff_vs_save, or site_plan, which is the primary routing decision an agent faces.

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

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

With no annotations, the description carries the full burden and does unusually well conceptually: it defines nameplate vs the 300 s productivity-weighted measured figure, explains why both are returned, and documents the 'starved' labeling rule for dry-fuel generators whose monitor reads zero. It omits operational traits like permissions, cost, or latency, but the analytic semantics are genuinely disclosed.

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

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

Front-loaded with the core comparison, then the explanation of the two figures and the starved exception. Slightly verbose in places ('Both are shown because they answer different questions'), but no sentence is empty.

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 and no annotations, so the description must carry return-value and safety information; it conveys the report's contents (both figures, starved grouping) but never addresses the two undocumented input parameters or confirm this is a read-only query. Adequate for the conceptual core, incomplete around inputs.

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 as_of carries a schema description (33% coverage); save and world are undocumented in both schema and description. The description adds no parameter meaning at all, so it does nothing to 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 line names the resource and scope precisely: generation capacity versus machine draw, in both nameplate and measured form. It is clear this returns a power analysis of a save, though it never explicitly differentiates itself from power-adjacent siblings like factory_health or world_summary.

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

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

There is no statement of when to call this versus alternatives, nor any prerequisite or context cue. The description explains what the numbers mean once you get them, but not why or when an agent should reach for 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?

With no annotations, the description carries the full behavioral burden. It discloses that the answer reports held, committed and free shards and whether the free pool covers a plan, but it does not state that this is a read-only query, nor does it describe pagination behavior or any side effects.

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

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

The description is two tight sentences with no filler. It front-loads the output content and then explains the overclock-plan computation, so every sentence earns its place.

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

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

For a tool with 7 parameters, no annotations, no output schema, and 29% schema coverage, the description is too thin. It covers the core shard accounting and plan cost, but omits parameter guidance, read-only status, and pagination or return-shape details an agent would need.

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 29% (7 parameters, only as_of and limit have schema descriptions). The description adds meaning for plan_machines and plan_clock, but leaves save, world, offset, and the relationship between limit and offset unexplained, so it does not compensate for the low coverage.

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

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

The description states a specific resource (Power Shards) and what is reported: held, committed, free, and the cost of an overclock plan. It clearly tells an agent what the tool computes, though it does not explicitly differentiate itself from the sibling power_report tool.

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

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

Usage is implied by the explanation that plan_machines at plan_clock costs shards per machine and the answer says whether the free pool covers it. There is no explicit when-to-use statement, no when-not-to-use guidance, and no named alternative among the many sibling 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?

With no annotations, the description carries the full burden and discloses several key traits: the signals combined, validation metrics, that it never merges factories but only splits them, and that the '#' column remains stable across pagination. It stops short of explicitly confirming read-only behavior or explaining whether any persistent state is modified.

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, and the rest is mostly useful behavioral context. The validation statistics are somewhat verbose, but they support trust in the proposal quality and do not bury the main point.

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 annotations and no output schema, the description covers core behavior, follow-up action, and unnamed filtering adequately. It remains incomplete on several input parameters and does not fully describe output structure or side effects.

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 43%, so the description needs to compensate but largely does not. It explains unnamed_only and pagination stability, but leaves save, world, as_of, offset, and max_span_m without added meaning beyond the sparse 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 states a specific verb and resource: it proposes factories by agglomerating a coherence score over signals. It is clearly not a general factory-list or query tool, but it does not explicitly differentiate itself from siblings like factory_query or list_factories.

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 follow-up guidance ('Use name_factory on what it proposes') and a use case for unnamed_only=True ('what have I built and not named'). However, it does not state when to call this tool instead of alternatives such as factory_query 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses the scoring inputs (reachable capacity, spread, distance to existing buildings, purity mix), that components are exposed for re-weighting, and that the result set is non-pageable by construction. It does not discuss permissions or whether it is purely read-only, but the ranking framing makes the operation's nature clear.

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

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

Front-loaded with purpose and scoring method, then usage and paging caveats in short paragraphs. Slightly padded by the double-backtick formatting and a couple of stylistic asides, but every 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?

For a 7-parameter tool with no annotations and no output schema, the description covers ranking semantics and the non-paging contract well but omits the meaning of the required `resource` param and the `save`/`world`/`as_of` world-state controls, leaving gaps an agent must guess at.

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% across 7 params, so the description must compensate. It adds real meaning for `sources` (same selectors as search_resource_nodes; omit to search whole map) and `limit` (raise rather than offset), but leaves `resource`, `save`, `world`, and `as_of` unexplained beyond sparse schema text.

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

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

States a specific verb and resource ('Rank candidate fields for a new extraction site') and immediately differentiates from siblings by referencing search_resource_nodes selectors and contrasting with paging behavior. An agent can distinguish it from factory_sites, site_plan, or search_resource_nodes without opening a schema.

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

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

Gives clear usage context: omit `sources` to search the whole map, reuse search_resource_nodes selectors, and raise `limit` rather than seeking an offset. It stops short of naming when NOT to use it versus close siblings like site_plan or factory_sites, so no explicit 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?

With no annotations, the description carries real weight and does so: it explains the counterfactual method, that zeros are meaningful answers, that deltas are an UPPER bound assuming unbuilt machines, and that pending-hard-drive alternates are flagged. It omits cost/latency given it solves the plan once per candidate over up to 25 rows, so it is not fully transparent, but the behavioral disclosure is unusually rich.

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, then caveats that each earn their place (zero-as-answer, upper bound, hard-drive flag). Slightly essayistic in tone, but no sentence 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?

For a 21-parameter, no-output-schema tool, the description explains what the deltas mean but never sketches the shape of the result (one row per candidate? what columns?) or how a plan/world is identified among the many optional arguments. Adequate for intent, incomplete for invocation.

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

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

Schema description coverage is only 24% across 21 parameters, so the description is expected to compensate and does not. Terms like 'candidate' and 'plan' are used informally, but nothing explains plan, as_of, limit, query, world, or the many planning knobs (sloops, exports, objective, machine_cost_mw) — the agent is left to guess at most arguments.

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 precise verb+resource (rank unlock candidates by marginal value to a given plan) and immediately differentiates from a tier list. An agent can distinguish it from siblings like alternates_for_item or compare_recipe_options without opening any schema.

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

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

The framing 'which unlock should I chase' with a plan-relative number implies the usage context, and the hard-drive flagging hints at the claimable-now case. But no sibling is named and there is no explicit when-not-to-use guidance (e.g., versus advise_hard_drive_pick or alternates_for_item), leaving the routing 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?

No annotations are provided, so the description bears full responsibility. It does disclose a notable behavior: the tool accepts a display name and resolves it internally, which is nontrivial. Yet it omits other behavioral details such as error handling (e.g., what happens if the name is not found), case sensitivity, or the exact structure of the returned data. This is adequate but not thorough.

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 first sentence is a model of conciseness, delivering the core purpose in under 10 words. The second sentence is longer and argumentative, defending the design choice to accept display names. While it adds useful context for an AI agent, it could be trimmed without losing essential guidance. Overall, it earns its place but is slightly verbose.

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 single-parameter lookup tool with no output schema, the description gives a good sense of the return fields (rates, machine, power, unlock source) and the accepted input. It does not mention error cases, but the tool is inherently simple and the description covers the key aspects. A short note on not-found behavior would make it complete.

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

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

The schema provides only a parameter name and type with no description (0% coverage). The description fully compensates by stating that the parameter accepts either a class ID or a display name, and even explains the trade-off. This is critical semantic information that the schema lacks, making the parameter's behavior completely clear.

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

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

The description clearly states the tool's purpose: providing exact numbers (rates, machine, power, unlock source) for a single recipe. This distinguishes it from siblings like search_recipes (which searches) or compare_recipe_options (which compares multiple recipes). The scope is specific to one recipe's details.

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 intended use case is implicit but clear: when you need exact numbers for a specific recipe. The description also explains that you can pass either a class ID or a display name, avoiding unnecessary round trips, and references match_recipes as an existing pattern for resolution. However, it does not explicitly say when to avoid this tool in favor of alternatives (e.g., for searching or comparison).

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that machines are untouched, nothing re-anchors, the label keeps anchors/notes/centroid/signature/dates, stored plans follow the new name, and name collisions are refused with an explanatory message. It stops short of stating permissions or idempotency, keeping 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 core facts (rename label, machines untouched, plans follow, collision refused) are front-loaded, but the second paragraph's aside about 'correcting one used to mean naming the whole selection again' is narrative padding that doesn't help an agent decide or invoke.

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?

Behavioral side effects are covered well for an unannotated tool with no output schema, but three of five parameters (save, as_of, world) are left undocumented by both schema and description, so the definition is not complete enough to invoke confidently.

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 40% across 5 parameters. The description implies the 'name'/'to' pair but never names them, and says nothing about save, as_of, or world. It does not compensate for the documentation gap the schema leaves.

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

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

The description opens with a specific verb+resource: 'Rename a factory label.' An agent immediately knows the operation. However, it never distinguishes itself from close siblings like name_factory or amend_factory, so the sibling boundary is left implicit.

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 or when-not-to-use guidance. The description mentions a collision case (renaming onto an existing name is refused) but does not tell the agent when to reach for rename_factory versus name_factory or amend_factory. Context is implied at best.

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

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

With no annotations, the description carries the full burden and does well: it declares the mutation is narrowly scoped, that nothing is re-solved, and enumerates what is preserved (key, recorded field, siting, notes). It omits permissions/error behavior and the base_rev concurrency requirement, so it stops short of a 5.

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

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

Purpose is front-loaded in the first sentence, and the rationale that follows is short. The second sentence is slightly run-on and rhetorical ('forgetting the first'), but it earns most of its space by explaining the non-effects.

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 what-changes/what-doesn't question well for a mutation tool with no annotations and no output schema. But with 6 parameters at 50% coverage and no output schema, the definition leaves parameter usage and success/return behavior uncovered, so it is 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?

Schema coverage is only 50% and the description adds no parameter-level meaning at all. It never clarifies the crucial distinction between the 'name' parameter (which plan) and 'to' (the new name), nor the roles of save/world, leaving half the parameters undocumented 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?

States a specific verb and resource ('Rename a saved plan') and immediately scopes it by declaring what does not happen ('Nothing is re-solved and nothing else about it changes'). An agent can distinguish this from the factory-naming siblings (rename_factory, name_factory) purely from the resource noun.

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 second sentence gives motivating context for when renaming is the right move ('a name is the only thing here a player picked, and it was the only thing they could not correct'), which implies usage. However, it never explicitly names an alternative (e.g. amend_factory, plan_factory) or states a when-not condition, so routing is left to inference.

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

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

With no annotations, the description carries the full burden, and it does so well: it discloses ordering ('longest first'), the columns returned (both ends, drawn length, elevation span, what it ends on), that proximity is measured against drawn lines not corner points, and that lists page via offset with a truncation line naming the next offset. It omits nothing critical behaviorally, though error/auth behavior is unaddressed.

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 and organized into one paragraph per concern, which is good structure for a 12-parameter tool. However it carries rhetorical padding ('the tail of that list is as real as its head', 'the web map has drawn these all along') that does not help an agent invoke it, so not every sentence earns its place.

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

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

For a 12-parameter tool with no output schema and no annotations, the description covers the core flow and the return shape adequately. But it never mentions `conduit_kind`, which is the central filter distinguishing belts from pipes, nor `save`/`world`, leaving real gaps an agent would have to infer.

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

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

Schema coverage is only 67%, but the description compensates for the key parameters: it details the accepted forms of `near`/`to` (metres coordinate, 'me', named factory, run id like 'chain:7'), explains that run ids centre on the run midpoint so `connects` ids can be followed call-by-call, and notes that `radius_m`/`to` do not narrow the networks view. It is silent on `conduit_kind`, `save`, and `world`.

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 -- 'belt and pipe runs near a point or between two areas', plus a second mode ('show="networks"' returns fluid networks). An agent can tell exactly what class of object is returned. It never names a sibling tool (e.g. show_on_map, trace_upstream) to differentiate, 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?

Gives clear context for use -- it frames the tool as the text answer to 'is there a pipe between those extractors and that platform' -- and explains when each mode applies ('show="networks"' answers the other size of question). It also states the condition that selects the `to` filter. It lacks explicit when-NOT-to-use guidance and never compares to alternative 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the return fields but does not mention pagination, sorting, matching behavior, result limits, or any side effects. For a search tool, this is minimal transparency.

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

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

The description is two short sentences, front-loaded with the action and return fields. It contains no unnecessary words or repetition of schema details.

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

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

Given no output schema and no annotations, the description should explain the result format and pagination behavior. It lists return fields but not their structure (e.g., array vs object) or how limit/offset affect results. The description is too sparse for a search tool with 3 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 33%, with only 'limit' documented. The description clarifies that 'query' is for the item name but provides no meaning for 'offset' or additional details on limit/offset behavior. Thus, it does not compensate adequately for the low schema coverage.

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

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

The description uses a specific verb ('Find') with the resource 'items' and method 'by name,' clearly stating the tool's function. It mentions the return fields (form, energy, sink points), adding specificity, though it does not explicitly distinguish from sibling tools like search_recipes.

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 is provided on when to use this tool compared to alternatives such as search_recipes, recipe_detail, or alternates_for_item. The description only states the action, leaving the agent to infer usage context.

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

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

With no annotations, the description carries the full burden and does add real behavioral context: that results are marked HAVE/LOCKED and that header counts aggregate EVERY recipe kind regardless of the recipe_kind filter. It still omits return shape and pagination behavior, but the non-obvious counting quirk is exactly the kind of disclosure that matters.

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 purpose statement followed by two tightly scoped clarifications with inline code examples. No filler sentences and nothing buried.

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?

A 12-parameter tool with 33% schema coverage, no annotations and no output schema needs substantially more than this. Undocumented booleans like include_events and only_alternates, plus save/world/as_of scoping and pagination via limit/offset, are left 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 only 33%, so the description must compensate and it partly does — clarifying consumes/produces semantics that the bare schema does not. But query, save, world, as_of, include_events, only_alternates, limit and offset get no explanation beyond their name/default, leaving a significant 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 (search recipes) and two distinct search modes: by name and by consume/produce relationships. It clearly is not search_items or recipe_detail, though it never names those siblings to sharpen 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?

It explains one usage nuance well — that ``consumes="Rubber"`` is the reverse lookup for recipes that eat an item — and describes recipe_kind values. However it gives no guidance on when to use query vs consumes/produces, or when to prefer recipe_detail over a search.

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

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

With no annotations the description carries the full burden, and it discloses real behavior: stable ranking, offset paging, a hard 25-row cap, that `near` adds a distance column in any view, and the water exception where non-node fracking satellites plus sea level are returned instead. It does not state read-only-ness or auth/side-effect profile, 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?

Front-loads the three-view framing, then groups selector syntax and paging compactly. It is long but nearly every block (selector grammar, near semantics, water exception) earns its place; only the water aside feels slightly tacked on.

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

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

For a 14-param, no-annotation tool with no output schema, the description covers query construction, mode selection, paging, and notable return quirks (distance column, printed sea level). It stops short of describing the shape of a `fields` cluster row or several lesser parameters, leaving some gaps.

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

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

It adds substantial meaning for `sources` (union of locations, intersection of filters) with syntax examples, and clarifies `near` and `offset`. But at 57% schema coverage across 14 parameters, several (save, world, as_of, purity, only_free, resource, kind) are left entirely to the schema, so the description only partially compensates.

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

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

The description states a specific resource (resource nodes) and lays out its three modes precisely, including the question each answers ("where is there a lot of iron", "what is closest"). An agent knows exactly what it retrieves. It never names a sibling tool or draws an explicit boundary against search_items/search_conduits, so it stays 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 gives clear in-tool routing: fields for abundance, nodes for reusable ids, nearest for proximity, with the requirement that nearest needs `near`. It also gives worked query examples ("the nearest free coal to the coal powerplant"). It does not state when NOT to use this tool versus the many other search_* 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?

With no annotations, the description carries the full burden. It usefully discloses two behaviors beyond expectation: product selectors over-match (construction feed inside the steel site) and `slab:<n>` describes an empty platform rather than refusing. However it never states the tool is read-only/preview-only in safety terms, nor how results are returned, leaving gaps for a 6-param tool with zero annotation coverage.

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

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

Front-loaded with the core purpose, then one grounded example and one edge-case note. Every sentence carries information; the Concrete example is a bit long but earns its place by teaching the over-match trap.

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 and no annotations, so the description must carry the load. It covers purpose, the key selector gotcha, and slab behavior adequately for a preview tool, though it omits read-only framing and the meaning of save/world/as_of parameters, which an agent would still need.

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 meaningfully supplements it: it explains the semantics of product-based selectors (over-matching and how they resolve) and the special `slab:<n>` term including its empty-platform behavior. It does not address save/world/as_of/split/expand, but it adds real semantic value beyond the schema's terse term list.

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 adds the dry-run framing 'before naming them,' which signals it is the read-only preview preceding naming tools. It's clear, though it doesn't name the specific sibling (e.g. name_factory) it pairs with.

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

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

'Worth running first on anything product-based' gives an explicit when-to-use condition and the concrete example (Concrete pulling 17 machines with only one intended) tells the agent exactly when this tool adds value. No explicit when-not or named alternative, 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?

With no annotations, the description carries the burden and does so well: it discloses that two links are returned, what each exposes (saved base vs vanilla world), that `resource:` switches overlays, and that only Crude Oil layer tokens are confirmed while a wrong token still opens the map at the right place. Missing only auth/side-effect framing, though this is plainly a read-only link generator.

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-link purpose, then scoped to the `at` vocabulary and token caveats. It is prose-heavy and a touch long, but each paragraph adds decision-relevant detail rather than 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 6-parameter tool with no annotations and no output schema, the description adequately covers what the tool does, its return shape, and the key `at` semantics. The gaps are the undocumented save/zoom/world parameters, but the core invocation surface is well 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%. The description adds real meaning for `at` (the `resource:<name>` kind, docs pointer) and for layer tokens/overrides, but `save`, `zoom`, and `world` are undocumented in both the schema and the description, leaving half the surface 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?

Opens with a specific verb+resource: it produces two map links (local project map and the public satisfactory-calculator.com one) centred on a place. It clearly distinguishes what each link shows and names the sibling vocabulary it reuses, so an agent immediately knows what the tool yields.

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 place vocabulary shared with other tools (docs/selectors.md) and the one `resource:<name>` exception, which implies usage. However it never states when to pick this tool over siblings like describe_location, whereami, or factory_map, nor any when-not condition.

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?

No annotations exist, so the description carries full burden, and it delivers: it states the siting is a RECORD of a decision, that re-running the plan neither reads nor moves it, that save_as over the same name preserves it, and that the record tracks measured-vs-derived provenance. Missing permission/error or base_rev conflict behaviour 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.