SatisfactoryMCP
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation3/5
Most tools are clearly distinct, but several revolve around factories and plans: factory_map and propose_factories both output proposed factories, and factory_sites/list_factories add to the ambiguity. Long descriptions help, but an agent could still misselect between these overlapping tools.
Naming Consistency4/5Names are consistently lowercase snake_case, and most follow a verb_noun structure (list_plans, search_items, plan_factory). However, there are several noun-only names (factory_map, power_shards, somersloops, whereami, bom) that break the pattern, though they remain readable and predictable.
Tool Count2/5With 42 tools, this is well above the 15-tool well-scoped range and into 'too many' territory. While each tool is specialized, the large number creates significant selection overhead and many tools are near-neighbors (factory_map vs propose_factories, plan_factory vs plan_layout vs diff_vs_save).
Completeness5/5The tool surface comprehensively covers the Satisfactory domain: factory analysis, planning, recipes, resources, power, world state, collectibles, and progression. There are no obvious dead ends—each major workflow has the necessary support, and the read-only nature is clearly stated.
Average 3.6/5 across 42 of 42 tools scored. Lowest: 2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 333 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It adds the detail that buildings are 'built' and clustered into sites, ordered 'largest first', but it does not state whether this is a read-only operation, what the output format is, or how filtering such as 'save' and 'world' works. This is insufficient given 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Built production buildings clustered into sites, largest first.'), but it is under-specified rather than concise. It omits essential information and does not read as a complete instruction, making it similar to the 'under-specification' case in the calibration examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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 is the only source of context. It does not mention return format, how 'sites' are represented, the effect of 'save' or 'world' filters, or any side effects. For a tool with three parameters, this is completely inadequate for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'limit' having a description. The description does not explain the 'save' and 'world' parameters, nor does it add any meaning beyond the schema. It fails to compensate for the low coverage, leaving the agent without necessary parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description phrase 'Built production buildings clustered into sites' is a noun phrase rather than an explicit verb like 'list' or 'get', making the action ambiguous. It does convey the data scope (production buildings, sites) and ordering ('largest first'), which is more informative than a tautology, but it still fails to clearly state what the tool actually does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, scenarios, or exclusions, and does not reference sibling tools such as 'factory_map' or 'list_factories'. This gives the agent no context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explicitly state that this is a read-only operation, nor does it explain side effects, permissions, or return format. The phrase 'whether the world has moved under them' gives a hint about an additional status, but this is not fully explained and is more about output content than behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, but it is under-specified and cryptic. While it is not verbose, the brevity comes at the cost of clarity, and the sentence does not provide a complete or well-structured explanation of the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 optional parameters, no schema descriptions, and no output schema, the description is severely lacking. It does not explain the meaning of the parameters, the output structure, or any contextual details needed for correct usage. This is inadequate for a tool with even moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. However, it only vaguely references 'this world' (possibly aligning with the 'world' parameter) and does not explain the 'save' parameter at all. The agent has no semantic understanding of what 'save' or 'world' mean, making the tool hard to invoke correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Plans saved for this world, and whether the world has moved under them' is a noun phrase that lacks a specific verb, relying on the tool name 'list_plans' to convey the action. It communicates the subject matter but does not explicitly state 'list' or 'retrieve', making it somewhat vague. It does distinguish from siblings by focusing on plans, but the purpose is not as crisp as a verb-driven description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions. With a large sibling list including 'list_factories' and 'list_worlds', the description fails to clarify when 'list_plans' is the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that the per-phase item table is deprecated and frozen, and advises reading the header line first, which gives some behavioral context. However, it does not explain the output format beyond the header, nor whether the operation is read-only or if there are 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) but not well-structured. The first sentence is a fragment and cryptic, while the second provides essential context. It is not front-loaded with a clear action statement, and the phrasing is awkward, though it is compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool with no output schema and no annotations. It does not explain the meaning of 'phase' or the distinction between 'live' and 'deprecated' records. It hints at a header line but does not describe the actual return data, making it hard for an agent to predict the tool's output or use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description ignores the two parameters (save, world). It adds no meaning to their purpose, default behavior, or allowed values. The description is entirely about data semantics, leaving parameter semantics completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description hints that the tool shows Space Elevator requirements, distinguishing live and deprecated records, but it lacks an explicit verb (e.g., 'returns', 'lists') and does not clearly state what the tool does. It is somewhat differentiated from siblings by focusing on Space Elevator phases, but the purpose remains vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or exclusions. The only implied context is that the per-phase table is deprecated, but it does not tell the user when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It states the data is 'stored in the save' and includes 'rerolls left', implying a read-only operation, but it does not explicitly confirm that the tool only reads data, how it handles missing save/world parameters, or any side effects. The description is more of a data definition than a behavioral specification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of about ten words, with no filler or redundancy. It front-loads the key term 'pending hard-drive choices'. However, it is arguably too terse and could devote a few more words to clarifying the action or return type without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two optional params, no output schema, no annotations), but the description is still incomplete. It does not state what the return value looks like (e.g., a list of choices with reroll counts), what 'pending' means in this context, or how the optional parameters affect results. Sibling tools and naming suggest a listing operation, but the agent would need additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two parameters, 'save' and 'world', with zero description coverage. The description only references 'save' (via 'stored in the save') but does not explain the role of 'world' or how either parameter should be used. Since the description fails to compensate for the schema's lack of parameter documentation, it adds minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as pending hard-drive choices stored in the save, with rerolls left. Although it lacks an explicit verb, the tool name 'list_' provides the action, and the description adds specific scope. However, it does not explicitly distinguish from sibling tools like '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.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'advise_hard_drive_pick' or 'compare_recipe_options'. There is no mention of prerequisites, exclusions, or recommended scenarios, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It mentions the content categories (progress, power, problems) but does not state whether this is a read-only operation, what side effects it may have, or any permissions required. The lack of annotation and minimal behavioral info leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no filler or redundant information. It is front-loaded and to the point, earning its place by providing the core idea without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sparse schema (no parameter descriptions) and no annotations or output schema, the description is insufficiently complete. It does not explain what the parameters do, what the returned summary looks like, or what 'progress', 'power', and 'problems' entail. The tool may be simple, but the description leaves too much unsaid for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its two parameters ('save' and 'world'), and the tool description does not explain what these parameters mean or how they relate to 'for one world'. The description fails to compensate for the schema's lack of parameter semantics, leaving the agent without guidance on how to populate them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Progress, power and problems for one world' clearly indicates the resource (one world) and the content scope (progress, power, problems). It distinguishes from siblings like list_worlds by stating 'for one world', though it lacks an explicit verb like 'summarizes' or 'gets'. Overall, it's clear but not maximally specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of alternative tools like factory_query or list_worlds, nor any exclusion criteria. It simply describes the output without contextualizing the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that the tool defaults to alternates and never returns all 872 recipes, which is useful. However, it does not explicitly state that this is a read-only operation or describe side effects, though the query-like nature implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is not bloated. However, it is under-specified, omitting essential parameter details and use-case context. It is not as incomplete as a tautology, but it sacrifices necessary information for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is insufficient. It does not explain the return format, the role of save and world parameters, or what 'alternates' means, leaving significant gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%), and the description does not compensate. 'Defaults to alternates' restates the schema default for only_alternates, and 'never all 872' relates to the limit cap already present in the schema. The save and world parameters remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Which recipes this world has' clearly identifies the resource (recipes) and scope (world), implying a query/list operation. It is understandable but lacks an explicit verb like 'list' or 'get' and does not differentiate from sibling recipe tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as 'search_recipes' or 'recipe_detail'. The phrase 'Defaults to alternates, never all 872' hints at a limitation but does not state suitable use cases or direct users to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description is the sole source of behavioral info. It discloses that when a save is readable, each row is marked HAVE or LOCKED, providing context about save-dependent output. However, it doesn't mention error behavior, exact output format, or implications of include_locked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, but the first sentence is grammatically awkward ('alternates first'). Still, it's compact and front-loads the core behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 leaves many gaps: what the response looks like, how HAVE/LOCKED is determined, how include_locked affects results, and what happens if save isn't readable. It's incomplete for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description references 'item' and 'save' only indirectly and does not explain include_locked. It fails to compensate for the lack of parameter details in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool lists every automatable recipe that makes an item, with alternates first. It conveys a specific action and resource, though not as clearly as a verb like 'list'. It distinguishes itself from sibling tools by emphasizing the alternates-first ordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 versus alternatives like recipe_detail or compare_recipe_options. The description implies it's for overviewing recipe options for an item, but doesn't state exclusions or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explains the counting methodology (counting slot contents rather than inverting a boost multiplier) and that free/committed counts are exact. It does not disclose the return format or confirm the lack of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively compact and front-loaded, with the opening sentence defining the scope. The historical paragraph adds context but could be trimmed; overall it is moderately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no parameter documentation, the description fails to explain what the tool returns or how save/world should be used. It provides good domain context but insufficient invocation guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two optional parameters (save, world) with zero description coverage. The description does not mention or explain these parameters, leaving a significant gap for an agent to know what values to pass.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys the tool reports somersloop counts across 'held, slotted and owned' categories and positions it as a sibling to power_shards. However, it lacks an explicit verb like 'get' or 'count', relying on the noun phrase and analogy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is the go-to for somersloop counts, noting the historical difficulty of discovering budgets, but it does not explicitly state when to use it or when to use alternatives like power_shards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full transparency burden. It discloses that the tool returns named factories with standing quantities, implying a read-only list operation. However, it doesn't explain how the 'save' and 'world' parameters affect results or whether it reflects the current filtered state, which is minimal but not misleading for a simple list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently states the purpose and output, though it omits details that would require additional length. This is appropriately concise for a tool of this apparent simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 covers the core purpose and output content but leaves gaps. It doesn't explain the optional parameters or the exact return structure. For a low-complexity tool, it's borderline adequate, but missing parameter semantics and usage alternatives prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only hints at world context via 'this world' and does not explain the 'save' parameter or how the parameters interact. The parameter names are somewhat self-explanatory, but the description adds little beyond the bare schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' with a clear resource 'factories' and adds distinguishing detail about tracking 'how much of each is still standing.' It conveys the tool's function effectively, though it doesn't explicitly differentiate from sibling tools like factory_map or factory_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 versus alternatives such as factory_map or factory_query. There is no mention of prerequisites, context, or exclusions—only the basic operation, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the calculation logic (plan_machines * plan_clock cost) and output elements (held, committed, free, coverage), which is useful. However, it does not disclose potential side effects, return format, or error behavior, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and consists of two short sentences. The second sentence is dense and somewhat cryptic, but still efficient without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description only partially completes the picture. It explains the main outputs and plan cost calculation but omits context for save/world parameters and fails to differentiate from power_report, leaving the tool underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, but the description adds meaning to plan_machines and plan_clock by explaining their relationship and how they affect the result. It does not elaborate on save, limit, or world, so those remain under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: reports power shards held, committed, free, and the cost of an overclock plan. It distinguishes from siblings like power_report by focusing specifically on shards and overclock cost, though it lacks a strong imperative verb like 'list' or 'get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or alternative tools like power_report, so the agent is left to infer usage from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: rows are marked HAVE or LOCKED against the save when readable, and it elaborates on the severe consequence for logistics planning. This goes beyond a simple listing description and provides actionable insight into output semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. The first sentence states the core purpose; the second provides a crucial caveat with a concrete example of why it matters. Every sentence earns its place; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema or annotations, the description gives meaningful context: the building kinds, the HAVE/LOCKED status mechanism, and the logistics pitfall. It does not describe the exact return format or all parameter effects, but for a list tool, it adequately covers the most important behavioral nuance. The guidance is sufficient for many use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially explains the 'kind' parameter by enumerating its possible values (production, extractor, generator, logistics). However, it does not explain the 'save' or 'world' parameters, leaving significant ambiguity about their roles. This is insufficient for a 3-parameter tool with zero schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Buildings by kind' is a noun phrase rather than a clear action statement, though it does convey that the tool returns buildings categorized by kind. It lists the kinds (production, extractor, generator, logistics) but does not explicitly say 'list' or 'retrieve'. This somewhat distinguishes it from sibling list tools by focusing on building categories, but it lacks a clear verb and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool vs alternatives. The second paragraph warns about the HAVE/LOCKED marking for logistics, implying the tool is useful for planning, but it does not state when to prefer this tool over siblings like list_factories or select_machines. No exclusions or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries a heavy burden. It explains the counterfactual LP methodology, the per-objective delta reporting, and the baseline equivalence with plan_factory. These are meaningful behavioral details, though it does not mention side effects, permissions, or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized across three paragraphs. The first sentence is clear and front-loaded, but the middle paragraph explaining objectives could be more concise. The third paragraph about sources is necessary but could be integrated more tightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the output style (per-objective deltas) and baseline behavior, but lacks details on the exact return format and the roles of save and world parameters. Given the tool's analytical complexity, a bit more structural detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description only explains the 'sources' parameter, noting it is plan_factory's selector list. Other parameters (save, world, hard_drive_id) are not described, leaving substantial gaps for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Rank one pending drive's options by marginal value, via counterfactual LP', which is a specific verb+resource+scope. It clearly distinguishes this tool as focusing on hard drive choice ranking, though it does not explicitly contrast it with sibling tools like list_pending_hard_drive_choices or rank_unlocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when there is a pending hard drive choice, but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusions, so the usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavior (machines are unaffected) but omits irreversibility, permissions, and side effects on related plans or references. This is helpful but incomplete for a delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clean sentence that front-loads the action and adds a clarifier. It is appropriately sized with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no annotations or output schema, the description is insufficient. It fails to explain the roles of 'save' and 'world' or any prerequisites or consequences beyond the label removal, making it inadequate for a 3-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (name, save, world). 'Name' is somewhat inferable from the tool name, but 'save' and 'world' are entirely unexplained, leaving the agent without critical context for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a factory label') and adds a scope clarification ('The machines themselves are untouched') that distinguishes it from destructive alternatives. This is a specific verb+resource pair with no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'machines untouched' phrase implies a safe deletion scenario, but the description offers no explicit when-to-use guidance or alternatives. It doesn't mention sibling tools like 'forget_plan', so usage context is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries a heavy burden. It discloses key behaviors: qty is a rate per minute, the output is computed via LP rather than tree expansion, and every row names the recipe chosen. This adds meaningful context beyond the schema. However, it omits other behavioral details like output format, pagination, or error conditions, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence states the purpose and output, the second adds crucial behavioral context about the algorithm and recipe independence. Every word earns its place, and there is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 9 parameters and no output schema. The description provides some critical context (the LP algorithm and the cycle problem) but is otherwise incomplete. It does not explain the parameters beyond qty, or describe the return structure, which is essential for a tool of this complexity. The description covers the 'why' but not the 'what' of inputs/outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 11%, and the description only clarifies the 'qty' parameter (stating it is a rate per minute). The other eight parameters (save, limit, world, outlets, allow_sinks, only_recipes, exclude_recipes) are left unexplained in both the schema and description. The description does not compensate for the low schema coverage, so the parameter semantics score must be low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Flattened bill of materials: total raw and intermediate rates for qty/min of an item.' This is a specific and informative purpose statement. However, it does not explicitly distinguish it from sibling tools like trace_upstream or recipe_detail, 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by explaining that it solves via LP and avoids expanding the recipe tree due to real cycles (Recycled Plastic and Recycled Rubber). This gives context about suitable scenarios but does not explicitly state alternatives or when not to use it, so it offers implied rather than explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It does disclose meaningful behavior: each route is solved end to end with the LP, and comparisons include raw resource per unit, whole buildings, net power, and byproducts needing an outlet. However, it omits potential side effects, computational costs, or how outputs are ordered, leaving some ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses line breaks for readability. Each sentence earns its place: the first defines the action, the second clarifies scope relative to a sibling, and the third details what the comparison includes. It could be slightly tighter, but it is well-structured and not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description is incomplete. It provides a high-level purpose but doesn't explain the output format, how routes are selected or ranked, or what the parameters control. The example ('Crude -> Alt HOR -> Diluted Fuel') helps, but operational details are missing, leaving the agent underinformed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 13% (1 of 8 params has a description), so the description must compensate. It fails to explain key parameters like 'outlets', 'allow_sinks', 'per_resource', or 'rate'. The mention of 'per resource' in the description is vague and doesn't clarify the parameter semantics, leaving most parameters underdocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Rank') and resource ('whole ROUTES to make an item') and clearly states the tool's scope: comparing routes by actual cost. It also distinguishes itself from the sibling tool 'alternates_for_item' by explicitly saying 'Not a recipe list', making its unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names an alternative ('alternates_for_item') and states what this tool is not ('Not a recipe list'), providing a clear when-not-to-use signal. However, it lacks an explicit 'use this when' scenario, so it stops short of the full when/when-not contrast expected for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains that the tool reports three independent signals rather than a single answer, and describes the strengths/limitations of each signal (e.g., power islands separate outposts but leave grown-together bases as a blob; foundation slabs are sharpest but ignore ground-built parts). This adds meaningful context about the tool's behavior and output semantics, though it does not describe the exact output format 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured: a one-sentence summary, an explanation of the three signals, and guidance on handling disagreements. Every sentence adds substantive meaning, and the prose is readable. It could be slightly tighter, but it is not rambling or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three signals) and the lack of annotations and output schema, the description provides a solid conceptual foundation but omits practical details such as what the result rows look like, how 'show' filters work, what save/world mean, and how limit is applied. It explains the 'why' but not the 'how' of invocation, leaving the agent with partial context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about the tool's own parameters (save, show, limit, world). The schema describes show and limit, but save and world are undocumented, and the description does not compensate. It mentions selectors (product:, near:, slab:) that apply to name_factory, not to this tool, so it provides zero parameter guidance. With 50% schema coverage, this is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool reports proposed factories derived from three signals: power islands, belt components, and foundation slabs. It clearly conveys the resource and scope, and implicitly indicates a reporting/list function. However, the absence of an explicit verb like 'list' or 'get' makes it slightly less direct than ideal, and it does not explicitly distinguish itself from sibling tools such as propose_factories, though it does mention name_factory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: when you want to see the three independent signals together, since none is right alone. It also explains how to handle disagreements by using name_factory with selectors (product:, near:, slab:). This gives clear context for choosing this tool over alternatives, though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly states a key behavioral trait: the delete operation does not affect the world state ('Nothing in the world is touched'). This is valuable for a destructive operation, though it doesn't address recoverability or confirmation prompts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted words. The primary action is front-loaded, and the safety clarification adds value without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with 3 parameters and no annotations or output schema, this description is too sparse. It omits the meaning of the optional parameters (save, world), any usage context, and what happens after deletion. This is insufficient for an agent to use it correctly in all situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. While 'name' obviously identifies the plan, the optional 'save' and 'world' parameters are left unexplained, which could lead to misuse if they are needed for scoping.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb+resource structure: 'Delete a saved plan.' This directly states what the tool does and distinguishes it from siblings like list_plans and plan_factory. The additional clarification 'Nothing in the world is touched' further narrows its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough to infer when to use it, but no explicit alternatives or exclusions are given. The comment 'Nothing in the world is touched' implies it is safe to use when you want to remove a plan without affecting the world, but the description doesn't explicitly say when to choose this over other plan-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses non-obvious behaviors, such as the reverse lookup for `consumes` and the header counting every kind regardless of the `kind` filter. This adds valuable context beyond a basic search description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with the purpose front-loaded in the first sentence and two short sentences explaining key parameters. Every sentence earns its place, and no unnecessary information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema, no annotations), the description is only moderately complete. It covers core search behavior and some parameter quirks but does not explain output format beyond HAVE/LOCKED marking, nor does it document many parameters. There are clear gaps for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for `consumes` and `kind`, but with 9 parameters and only 11% schema description coverage, many parameters (query, produces, limit, offset, include_events, only_alternates) remain unexplained. It partially compensates for the sparse schema but does not fully cover the parameter space.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool searches recipes by name or by consumed/produced items, which is specific and differentiates it from siblings like search_items. It also mentions a distinctive behavior ('Marks HAVE/LOCKED') that adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 versus alternatives. The description explains parameter behavior but does not mention when to choose search_recipes over search_items, recipe_detail, or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the staleness issue, the source pawn, and how to apply the result practically. It doesn't describe the output format or content details of 'around them', but the key caveat is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes only essential behavioral context. Every sentence adds value without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, a key staleness caveat, and a usage tip, but lacks information about return values, the meaning of 'around them', and details for save/world parameters. Given no output schema or annotations, this leaves meaningful gaps for a new agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only 'limit' has a description). The description hints at radius through `near:me,<radius>` but doesn't explain the radius_m parameter or the save/world parameters. It insufficiently compensates for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reports the player's standing position and nearby surroundings. It distinguishes from siblings like describe_location by focusing on the player's pawn location, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that position comes from the Char_Player_C pawn in the save and can be stale, giving important context for when the result is reliable. It also provides an explicit usage tip: using `near:me,<radius>` as a source selector in planning tools to scope work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 reveals that the label uses stable machine instance IDs, survives saves and moves, and that re-calling re-anchors. This transparently indicates a mutating operation (creating/updating a persistent label) without requiring inferences 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences. The first sentence immediately states the purpose, and the second adds essential behavioral details about persistence and re-anchoring. No fluff or redundant information is present, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core concept is well explained, but with 8 parameters and no output schema, the description leaves out critical details about what happens on first use vs. subsequent uses, the meaning of 'save', 'world', 'dry_run', and the exact behavior of 'split' and 'expand' (though partly covered in schema). It is adequate for understanding the tool's purpose but not sufficient for parameter-level usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 38%, so the description must compensate for the many undocumented parameters (name, save, world, dry_run, etc.). However, it only references 'the current selection' and provides no meaning for these parameters. The schema's descriptions for 'select', 'split', and 'expand' exist, but the remaining parameters are not explained anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core function: 'Name a set of machines and persist it for this world.' This is a specific verb-object pairing that distinguishes it from related tools like 'forget_factory' and 'list_factories'. The added detail about storing machine instance IDs further clarifies its unique role as a persistent labeling mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through persistence and re-anchoring behavior, but it does not explicitly state when to choose this over alternatives, nor does it provide exclusion criteria. It mentions that calling again re-anchors to the current selection, which is a useful contextual hint, but lacks direct comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the conceptual behavior (how measured is computed), but doesn't explicitly state whether the tool is read-only, possible side effects, or error conditions. It adds value but leaves some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence gives a clear summary, and the second paragraph adds needed explanatory detail without unnecessary fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core conceptual distinction, but falls short on return format (no output schema) and parameter usage. Given the tool's simplicity, it's adequately complete for a knowledgeable user, but an agent would need more details to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not mention the 'save' and 'world' parameters at all. The agent must infer their meaning from the tool name and optionality, which is insufficient given the schema provides no additional guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports generation capacity vs machine draw, with both nameplate and measured values. It explains the distinction in detail, making the tool's unique purpose evident even among many siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that measured values weigh by the 300s productivity monitor and are 'the one that says what is free right now,' giving clear context for when to use this tool. However, it doesn't explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 important quirks: only Crude Oil layer tokens are confirmed, others are flagged, and a wrong token still opens the map in the correct location. It also explains how resource names switch overlays. However, it does not mention what happens for an invalid target or whether any side effects occur (though a link generator is likely read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a clear explanation of target, and a focused warning about layer tokens. Every sentence adds value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a good overview of the tool's behavior and key parameter 'target', but it leaves gaps: no explicit output format (though 'map link' implies it), no explanation of the other parameters (save, zoom, world), and no list of valid layer tokens beyond Crude Oil. Given the lack of annotations and output schema, more detail would be needed for complete guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, but the description compensates by adding detail for the key parameter 'target' (coordinate in metres, 'me', factory label, node id, resource name) and explains the behavior for resource names. It also adds context for 'layers' (token confirmation caveat). However, 'save', 'zoom', and 'world' are not addressed in the description, limiting full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a satisfactory-calculator.com map link centred on a target with layers enabled. It is specific about the resource and action, but does not explicitly differentiate it from sibling tools like factory_map, which might also show map locations. The detailed target types (coordinate, 'me', factory label, node id, resource name) add clarity beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining what target can be (e.g., 'node id from search_resource_nodes') but does not state when to choose this tool over alternatives. It lacks explicit 'when to use' or 'when not to use' guidance and does not mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors: the hard power constraint, fuse-blowing consequence, generators drawing 0 MW, and reading from the save/dump. This goes beyond basic expectations, though it does not address side effects or exact output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, front-loading the core purpose and then explaining the critical constraint and consequence. Some phrasing ('removes most of the problem') is a bit extraneous, but each section adds necessary context for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 19-parameter tool with no output schema and no annotations, the description lacks information about return values, how to interpret the resulting order, or details of the many parameters beyond a reference to plan_factory. The conceptual foundation is strong, but operational completeness is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 16% (3/19 params), so the description must compensate. It adds useful context by stating it accepts plan_factory's arguments, explaining the 'plan=' recall, and relating headroom_mw to the power constraint. However, most parameters remain without added meaning, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool determines the order to switch a built plant on without blowing the fuse. It explicitly contrasts STARTUP order with build order and notes 'Nothing here tells you what to build first,' which distinguishes it from sibling plan_factory. The verb+resource identity is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use after construction ('a built plant') and highlights the difference from build order, which guides when to use this tool vs plan_factory. It also mentions 'Takes plan_factory's arguments,' signaling shared context. However, it does not explicitly state exclusions or name alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and exceeds it. It discloses a subtle behavioral detail: production amplification has no save flag and is 'derived from the purchased-schematic set instead,' while overclocking is recorded as `mIsBuildingOverclockUnlocked`. It also explains that capability rows are marked LOCKS to distinguish gates from recipe additions, giving the agent meaningful insight into how results are computed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a concise summary, then provides explanatory detail. The technical note about save flags is somewhat lengthy but earns its place because it clarifies non-obvious derivation logic. Overall, it is well-structured and avoids redundancy, though it could be tightened without losing essential context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex and has no output schema, so the description must explain what the tool returns. It does so conceptually ('what is left, what it costs, and what you can afford right now') and adds domain-specific context about LOCKS and derived capabilities. It does not describe exact row structure or return fields, but given the rich explanatory detail, it is sufficiently complete for an agent to understand the tool's role and likely output shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level meaning beyond the input schema. With 60% schema description coverage, the schema already documents `limit`, `search`, and `status`, but `save` and `world` remain unexplained both in schema and description. The description focuses on domain concepts and does not help the agent understand how to pass parameters like `save` or `world`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear scope statement: 'MAM research: what is left, what it costs, and what you can afford right now.' It distinguishes this tool from recipe-oriented tools by emphasizing that the MAM holds CAPABILITIES 'as opposed to recipes' and that capability rows are marked LOCKS. However, it lacks a direct action verb like 'list' or 'show,' so it is clear but not maximally explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when investigating MAM capabilities rather than recipes, specifically noting which research costs and affordability are relevant. It implicitly contrasts with recipe-focused siblings by explaining the capability-vs-recipe distinction, but it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the ranking methodology (untapped REACHABLE capacity, spread, distance, purity mix) and that raw components are shown for re-weighting, with the caveat that 'the single score is a starting point, not a verdict.' It does not explicitly state read-only nature or discuss potential side effects, but the description implies a non-destructive analysis tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose statement, a short explanation of the scoring approach, and a focused note on the sources parameter. Every sentence adds meaningful information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must compensate. While it explains the purpose, ranking logic, and sources parameter, it does not describe the return format, meaning of 'spread' and 'purity mix,' or the remaining parameters (top, save, world). This leaves significant gaps for an agent to understand what to expect and how to use the tool fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains the 'sources' parameter (narrows search area using selectors from search_resource_nodes, omit for whole map). The other parameters (resource, top, save, world) are not described. With 5 parameters and only one explained, the description falls short of compensating for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Rank candidate fields for a new extraction site, best first,' which uses a specific verb ('rank') and resource ('candidate fields' for extraction sites). It clearly distinguishes itself from sibling tools like search_resource_nodes (which searches nodes) and propose_factories (which proposes factories) by focusing on scoring and ranking build sites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when evaluating candidate fields for a new extraction site. It also explains that 'sources' narrows the search area using the same selectors as search_resource_nodes, and that omitting it searches the whole map. However, it does not explicitly state when not to use it or name alternative tools for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses key behavioral rules: byproducts with no consumer make a plan infeasible, only solids can be sunk, fluids must be consumed exactly or packaged first, and recipes are split into world-unlocked vs not. This provides meaningful insight beyond a simple read-only hint, though it does not mention return format or 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short paragraphs, front-loaded with a clear purpose sentence. The second paragraph efficiently explains the underlying equality constraint and solids/fluids distinction. The third paragraph gives a practical usage tip. Every sentence earns its place, with no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers the core scenario and a key behavioral nuance (solids vs fluids), which is helpful. However, with 11 parameters and no output schema, it leaves gaps: most parameters are undocumented in both schema and description, and the return format is not described. It is adequate for understanding the main purpose but not fully complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9% (just 'limit'). The description explains only one parameter, 'item', with 'Pass item to focus on one byproduct instead of the whole plan.' The remaining 10 parameters (save, world, exports, sources, objective, etc.) are left entirely unexplained, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool explains which byproducts stall a plan and what can legally consume them. This specific verb+resource+scope distinguishes it from sibling tools like trace_upstream or alternates_for_item, which focus on tracing or alternatives rather than plan feasibility and legal consumption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear usage context: when a plan is infeasible due to a byproduct with no consumer. It also suggests using the 'item' parameter to focus on a single byproduct. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 the schematic-vs-blueprint scope, the absence of world coordinates/belt routing, throughput-based block splitting (with a concrete pipe-capacity example), and floor ordering with logistics decks. This is substantive behavioral context beyond simple action phrasing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is focused and front-loaded with the core purpose, then details modes and key constraints. The throughput example is concrete and illustrative, not filler. It is longer than two sentences but every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (25 params, no output schema), the description covers high-level outputs and constraints well but omits return format and many parameter details. It is adequate for selecting the tool but not fully comprehensive for invoking all options correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40% across 25 parameters, and the description adds meaningful semantics mainly for the 'detail' parameter, explaining each mode. The phrase 'Same arguments as plan_factory' references shared args but does not describe them individually, leaving many parameters without added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Turn a plan into a buildable schematic: blocks, buses and floors.' It clearly distinguishes itself from a blueprint and from sibling plan_factory by stating what it does and does not produce (modules, connections, floors, space budget vs. world coordinates/routing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that the tool shares arguments with plan_factory and enumerates the detail modes, giving clear context for selecting output granularity. It also warns that it is not a blueprint and lacks terrain data, so it is not for coordinate-level routing. However, it does not explicitly name alternative tools for blueprint-level work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 input signals, validation metrics (precision/recall), and a behavioral characteristic ('never merges two factories, only splits one'). It does not describe return format or side effects, but the tool appears read-only by design.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise paragraphs with the purpose front-loaded. The validation statistics are slightly tangential but add credibility. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite strong behavioral and usage context, the output format (structure of a proposed factory) is not described, and save/world parameters are not elaborated. With no output schema, this is a notable gap for an agent to invoke the tool and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only unnamed_only is explained with a practical use case, adding value beyond the schema. The other parameters (save, world, limit, max_span_m) are left to the schema, which covers only 40% of parameters. The description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: producing a coherence score over signals and agglomerating them into proposed factories. It differentiates itself from siblings by explicitly directing to 'name_factory' for naming and describing the 'unnamed_only' use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context is provided: use this to discover factory groupings and identify unnamed factories. However, it does not explicitly compare against alternatives like factory_map or list_factories, nor state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description compensates thoroughly: it explains that deltas are upper bounds, that unbuilt machines are assumed available and named, that pending hard-drive alternates are flagged, and that a zero result is meaningful. This is exceptional 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for the tool's complexity, with each sentence adding unique behavioral context. It is front-loaded with the core purpose and logically structured, making it easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the output concept (a number per unlock) and covers edge cases like zero and upper bounds, which is useful given the absence of an output schema. However, with 19 parameters and no annotations, the lack of parameter guidance makes it incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 16% (3 of 19 parameters), yet the description adds no parameter-level guidance. It references 'this plan' but does not explain save, world, clocks, sources, objective, or other parameters, failing to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks locked alternate recipes by their value to the current plan, answering 'which unlock should I chase' with a quantitative difference. It distinguishes itself from a tier list, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the use case as deciding which unlock to chase and explains why a tier list is inadequate. However, it does not name specific alternative tools or provide explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency weight and excels: it discloses the off-map/ocean behavior, explains the elevation is a sample with count/spread due to no heightmap, and details how ground vs built elevation differences indicate fill. This is honest and avoids overstating precision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: it leads with the core purpose, then provides necessary behavioral caveats in separate sentences. Every sentence adds value, covering edge cases and precision limitations without redundancy. Length is justified by the complexity of what it reports.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description sufficiently explains what the tool returns (region name, confidence, elevation sample count/spread, ground vs built). It also covers the 'off-map or ocean' edge case and the fill interpretation. The only gap is incomplete parameter documentation for save/world, but the description is strong for a read-only query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (radius_m has a description). The description mentions 'coordinate' which implies x_m/y_m but does not explain save, world, or radius_m. It adds meaning to x_m/y_m but leaves three parameters (save, world, radius_m) essentially unexplained beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Name') and resource ('region at a coordinate') and clearly states the dual function (region identification + elevation sampling). It distinguishes itself from sibling tools like whereami or list_regions by explicitly targeting arbitrary coordinates and returning 'off-map or ocean' instead of guessing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need region/elevation at a coordinate) but does not explicitly list alternatives or state when NOT to use it. It lacks explicit guidance like 'use instead of whereami when you have arbitrary coordinates' which would elevate it from implied to clear context with exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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 reveals measurement methodology (fixed 300-second window), defines uptime, explains every state in detail including non-obvious causes (e.g., 'dead node' from game updates), and gives a critical interpretation caveat about 'blocked' states. This is exemplary transparency beyond what structured fields could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: a one-sentence summary, a short measurement basis, a scannable list of states with parenthetical explanations, and a bold final caveat. Every sentence earns its place, with no fluff or repetition. The format aids quick comprehension despite the complexity of the domain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description adequately conveys the key output dimensions (uptime per machine and reason for stopped machines) and enumerates all possible states. It misses explicit return format details (e.g., how limit or factory filtering affects rows), but for a diagnostics tool with rich state semantics, it is nearly complete. Sibling-tool context reinforces its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about the parameters (save, limit, world, factory) beyond what the schema already provides. Schema coverage is only 50% (save and world lack descriptions), and the description does not compensate by explaining them or their roles in the query. The only indirect relevance is 'per machine,' but that does not clarify parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Measured uptime per machine, and WHY each stopped one is stopped.' It immediately distinguishes this tool from siblings by claiming 'The only measured numbers in this MCP.' This clearly identifies the tool's unique purpose, making it easy for an agent to know exactly what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It does not explicitly name alternatives or state when-not-to-use. However, it provides interpretive guidance on which states are actionable ('Blocked is not automatically a fault... Starved, stalled and no-recipe are the actionable ones'), implying the tool is for diagnosing actionable factory health issues. This is useful but lacks explicit comparison to sibling tools like factory_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses a read-only preview nature and reveals a non-obvious behavioral trait: a selector can match unintended machines (17 matching, only 1 the player's setup). It does not detail output format or side effects beyond the preview implication, which would push it to 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with a clear first-sentence purpose and a practical example that reinforces usage. Every sentence earns its place, and the structure fronts the key information effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity tool with no output schema, the description covers purpose and usage intent but lacks explicit return-value expectations or prerequisites. The illustrative example partially compensates, but an agent might still be uncertain about the exact output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level details, but the input schema provides useful descriptions for select, split, and expand. The optional save and world parameters are simple and self-explanatory, and the main selector syntax is fully documented in the schema, so the description need not duplicate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Preview which machines a selector picks, before naming them.' It uses a specific verb ('Preview') and resource ('machines'), and explicitly ties it to the naming workflow, distinguishing it from sibling tools like name_factory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides strong situational guidance: 'Worth running first on anything product-based' and illustrates the risk with a concrete example. However, it does not explicitly name alternative tools or state when not to use it, leaving the exclusion boundary implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden of behavioral disclosure. It clearly warns that region names are advisory and downsampled, potentially off by one grid cell, and directs users to exact grid cells for computation. This is a significant, non-obvious behavioral trait disclosed transparently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main purpose stated in the first sentence. The second paragraph adds important caveats about precision, which earns its place. It is not overly verbose, though the caveat could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional param, no output schema), and the description provides enough context: what it returns (named regions), optional filtering, and the critical advisory nature of boundaries. It does not explicitly describe the return format, but for a list operation, the purpose is clear and the caveat addresses the main ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'with_resource' with no description (coverage 0%), but the description explains it in plain language: 'optionally only those containing a given resource.' This adds semantic meaning to the parameter, compensating for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing named map regions with an optional filter for a resource. 'Named map regions, optionally only those containing a given resource' is specific about the resource ('map regions') and the verb ('list'). It does not explicitly differentiate from sibling tools, but the resource and filtering behavior are evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical guidance on when to use the tool: 'Use them to talk about places, not to compute with' and contrasts with exact grid cells available in node rows. This gives context for appropriate usage, though it does not name alternative tools or explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses how data is derived from the map and save files, explains the exactness of coordinates, the subtraction logic for remaining, and the never_streamed edge case for unloaded cells. This is substantial behavioral context, especially given there are no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead summary, bullet points for data sources, and clear mode explanations. Every section adds necessary context for a complex tool with six optional parameters, and the front-loaded summary immediately conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description explains what each mode returns (counts, lists with coordinates, distance-ordered lists) and mentions key fields like placed, remaining, and never_streamed. Some output shape details remain unspecified, but the behavioral coverage is thorough given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes mode, near, group, and limit. The description adds meaningful semantics for mode (defines each mode) and near (defaults to player), but leaves save and world parameters unexplained despite them lacking schema descriptions. With 67% schema coverage, the description only partially compensates for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool maps collectibles (slugs, somersloops, Mercer spheres, mushrooms, drop pods, loot caches) and reports counts, collected, remaining, and nearest. The verb 'Map' plus the specific resource categories distinguish it from siblings like 'somersloops' which likely focuses on a single category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the available modes (census, collected, remaining, nearest) and their defaults, providing clear context on how to invoke different behaviors. It does not explicitly name alternatives or say when not to use this tool, but the purpose is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is exceptionally transparent: it states the server keeps no state, actions are ordered free-first, power arithmetic is incremental, and machines are matched by identity rather than position. It also discloses that saves are read-only and there is no dismantle action, plus the limitation that built vs energized states are one-directional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense; each sentence adds a distinct behavioral detail. It could benefit from bullet points, but the prose is organized around matching, ordering, and state semantics, and contains little fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 19 parameters, no annotations, and no output schema, the description covers a great deal of behavior: identity matching, action ordering, incremental power, ranges for unidentifiable machines, stage grouping, and state semantics. It stops short of describing the full response structure, but within its scope it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
It says 'takes exactly plan_factory's arguments and re-solves', which orients users to borrow parameter knowledge from plan_factory. It also clarifies `plan=` and `stage=` beyond the schema (hash identity, stage numbering movement). However, it does not individually describe most of the other 17 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening phrase 'What to change to get from the factory you have to the one plan_factory plans' clearly identifies a diff operation between the current factory/save and a planned factory. It references plan_factory as the source of the target plan, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs how to recall a stored plan with `plan=` and how to narrow to a stage with `stage=<n>`, including special meaning of `stage=0`. It relates the stage grouping to commission_plan's partition, giving cross-tool context, though it does not state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the critical fact that rates are nameplate at saved clocks, not measured throughput, and a starved factory still reports full rate. It also clarifies the semantics of 'balance', 'inputs', and 'outputs' (sign/direction). It doesn't mention pagination or error behavior, but the disclosed nuance is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, uses compact bullet points for each 'of' option, and includes a necessary caveat about rates. Every sentence earns its place; no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex multi-faceted query tool with no output schema, the description explains the scope of results for each 'of' value (e.g., summary: size, position, top recipes, net power) and adds the rate caveat. It doesn't discuss the output format itself, but given the breadth, it is reasonably complete. Save and world parameters are not explained, but they appear to be context selectors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning to the 'of' parameter by explaining each option's scope (e.g., 'outputs: net surplus: it leaves the factory, or it backs up'). Schema coverage is 60%, but the description compensates by enriching the key parameter beyond the schema's simple list. It also clarifies 'factory' as a label or selector, which is already in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Ask one thing about one factory: what it makes, needs, draws, or touches.' It enumerates specific query categories (summary, balance, outputs, etc.) which both clarifies purpose and distinguishes it from sibling tools like factory_map or factory_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The first line implies usage for querying a single factory, and the 'of' parameter guidance explains how to request multiple aspects at once. However, there is no explicit 'when not to use' or comparison with alternative tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains mode-specific behavior, that nearest requires `near`, how `sources` union/intersect logic works, and that providing `near` adds a distance column. It does not mention side effects or safety, but for a read-only search tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and examples. Each sentence adds meaningful detail, and the content is front-loaded with the mode summary. It's informative without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functionality (modes, selectors, near coordinate semantics) and key edge cases (e.g., nearest requires near, distance column added). However, it omits several parameters (`save`, `world`, `purity`, `only_free`, `group`) and does not describe return shape, which could leave an agent uncertain about certain options despite the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 36%, so the description compensates extensively. It thoroughly explains `mode`, `near`, and `sources` with examples, and implicitly covers `resource` via the selector syntax. It lacks detail for `save`, `world`, `purity`, and `only_free`, but the core parameters are well documented beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as searching resource nodes and provides a breakdown of three distinct output modes (fields, nodes, nearest), each with a specific purpose and example. It distinguishes itself from sibling tools by focusing on resource-node discovery with location-based filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode (e.g., fields for finding high-yield clusters, nearest for proximity) and gives concrete selector examples. It doesn't explicitly name alternative tools or state exclusions, but the context is clear enough to guide selection among modes and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that direction is READ rather than guessed, explains the 92.5% connector direction rate and how extractors/generators settle the rest, and states the policy of walking edges BOTH ways when unsure. It also reveals that belts and pipes are traversed but omitted from output, including a concrete node/depth example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three focused paragraphs: purpose/differentiation, direction reliability, and filtering/performance. The cutover narrative adds clarity but is slightly verbose. Every sentence contributes a distinct insight, though the 92.5% statistic and depth example could be trimmed without losing core meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers purpose, usage context, directional behavior, and return filtering. It implies a table output and gives a sense of scale ('331 nodes at depth 72'), but it doesn't specify exact output columns or edge cases like cycles or disconnected seeds. Still, it is quite complete for a tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents seed, limit, and direction. The description enriches seed with 'one machine or one building type' and elaborates on direction behavior (up/down, BOTH ways fallback). However, save and world are left completely undocumented by both schema and description, and the 60% schema coverage means the description does not fully compensate for those gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'What feeds a machine, or what it feeds -- walked on the save's own connections.' It immediately distinguishes this tool from the sibling factory_query, stating that factory_query works between labelled sets while this one targets one machine or building type. The oil extractor/fuel generator example concretely illustrates the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly differentiates from factory_query: 'factory_query answers this between LABELLED sets. This answers it for one machine or one building type.' It also provides a practical cutover scenario, signaling when an agent should prefer this tool. It doesn't explicitly list exclusions, but naming the alternative is strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses many non-obvious behaviors: machine counts are rounded to whole buildings at a derived clock with exact ratios, 'exports' replaces the default and refuses unknown tokens, 'sloops' is a budget that spends optimally, and equality constraints make byproducts infeasible if unconsumed. These details go far beyond what annotations could provide and fully inform the agent of consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is densely packed with essential information, organized by parameter with inline examples. It is front-loaded with a clear purpose statement and each section earns its place, despite the length. The use of code blocks and examples improves scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 24 parameters and no output schema, the description covers the key behavioral and semantic aspects, including defaults, exception cases, and interactions. It explains machine rounding, power trade-offs, and edge cases like exports dropping MW. This makes it effectively complete for agent invocation, even without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 42%, the description compensates by deeply explaining the most critical parameters: sources, exports, sloops, clocks, extractor_clocks, machine_cost_mw, and logistics_items. For example, it clarifies that 'exports' is a whitelist that replaces the default and that 'sloops' is a budget, not a switch. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Optimise a factory with an LP over this world's unlocked recipes,' which uses a specific verb and resource, clearly stating the tool's function. It distinguishes itself from sibling tools by focusing on optimization over recipes, and even references search_resource_nodes for node discovery. This is a strong, specific purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive guidance on when and how to use parameters, such as explaining that 'exports' replaces the default rather than extending it and that 'sloops' is a budget. It also points to search_resource_nodes for discovering node ids. However, it does not explicitly state when to choose this tool over alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lukszi/SatisfactoryMCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server