dfhack-mcp
Server Quality Checklist
Latest release: v1.4.1
- Disambiguation4/5
Each tool targets a distinct subsystem (wiki, artifacts, burrows, etc.), and the extremely detailed descriptions make them individually clear. However, several tools overlap in reporting hostiles (threats, defenses, military) and terrain/water facts (environment, geology, fluids), so an agent could initially hesitate before picking the right one. The primary purposes differ enough that only minor confusion exists.
Naming Consistency4/5All names use consistent lowercase snake_case and are mostly plural nouns or noun phrases (e.g., stockpiles, rooms_and_zones). A few are verb+noun (find_unit, wiki_lookup) or a bare verb (identify), which is a minor deviation but still follows the same casing style and remains readable. The pattern is predictable overall.
Tool Count2/5At 37 tools, this server sits well above the 25-tool threshold the rubric marks as too many. While Dwarf Fortress is complex, several tools could be consolidated (e.g., threats/defenses/military, environment/geology/fluids), inflating the surface without a proportional increase in distinct capabilities. The count feels heavy rather than lean.
Completeness5/5The tool surface offers comprehensive read-only coverage of the loaded fort: units, labor, military, health, supplies, structures, trade, and world data. Chaining is well-designed (find_unit -> citizen, wiki_search -> wiki_lookup) and there are no obvious dead ends. The only missing features are actuator tools, which are outside this server's stated read-only scope.
Average 4.6/5 across 37 of 37 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 146 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under ISC License.
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
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses return value structure, edge cases (empty active, error), and clarifies the distinction between demand and stock ('it reports the demand vs. the stock, not what to go collect'). This adds meaningful behavioral context beyond a simple listing tool.
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 each sentence adds value: the first gives the core purpose, the second details output fields, the third explains a use case, and the fourth covers edge cases. It's structured clearly with a colon, but could be slightly tighter.
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?
With no output schema, the description fully specifies return values including structure, statuses, and error cases. It addresses the common case and error condition, making it complete for a read-only status tool.
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?
There are zero parameters, and the schema coverage is 100%, so a baseline of 4 is appropriate. The description does not need to explain parameter semantics because there are none.
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's scope ('Any active strange mood ... and its material countdown') and enumerates all mood types. It also differentiates from sibling tools by focusing exclusively on strange moods, a unique concern not addressed by nearby tools like fort_health or jobs_and_labor.
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 monitoring use through the 'early warning' phrase but never explicitly states when to use this over alternatives. It doesn't mention exclusions or alternative tools, though the uniqueness of the subject matter reduces the need.
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. It discloses grouping behavior, separation of active/contained threats, flags for specific danger types, and the pre-triaged alerts list. It also states the error response for no active fort, providing useful context beyond static schema fields.
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 and efficiently packs key information: the resource, output grouping, classifications, and error handling. It is front-loaded and every sentence contributes meaning, with no redundancy.
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?
Given no output schema and zero parameters, the description is complete for a list-returning tool. It explains the return content, categorizations, and error case, making it self-contained and sufficient for an agent to know what to expect.
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 0 parameters, so the baseline is 4. The description is not required to explain parameters, and it does not add parameter-related detail. The score reflects that no parameter documentation is needed.
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 lists dangerous units on the map, grouped by creature type, and details the specific distinctions it makes (active vs. contained, great-danger flags, invaders, undead). This is a specific verb+resource description that distinguishes it from sibling tools like 'military' or 'fort_status'.
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 use for assessing map threats but does not explicitly state when to use this tool versus alternatives or provide exclusions. It lacks a 'use this when' or 'for X, use sibling' note, but the detailed behavior helps infer its purpose.
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 fully discloses behavioral traits: returns an error if no fort is loaded, caps on routes and vehicles with truncation flags, sorting by id, and details about stale vehicle references. It covers edge cases and data semantics comprehensively.
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 lengthy but densely informative. Every sentence contributes to explaining the complex data structure. It is front-loaded with the core concept and then details nested objects. While a bit wordy, the detail is necessary for such a complex topic.
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?
Given the tool has no input schema, no output schema, and no annotations, the description provides a complete picture: the overall structure of routes, stops, vehicles, nested properties, thresholds, and error conditions. It is fully self-contained for an agent to invoke and interpret results.
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 per rubric is 4. The description provides no parameter-level details because there are none to describe, but it thoroughly explains the return value structure.
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: to retrieve the fort's minecart hauling infrastructure, including routes, stops, and vehicles. It distinguishes itself from sibling tools by focusing specifically on hauling routes and vehicle objects, not general stockpiles or stocks.
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 explains what data is returned and when an error occurs, but it does not explicitly compare itself to alternatives or state when to use this tool versus siblings like 'stockpiles' or 'work_order_list'. Usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/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 caps (20, 25), ordering (most-recent-first), degradation to empty lists, and the error response. It does not explicitly state 'read-only,' but the return-oriented language and lack of side-effect description imply a safe query.
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 dense but front-loaded with the core identity. It packs many details (fields, caps, order, edge cases) efficiently, though a structured list would improve scannability without losing content.
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?
Even without an output schema, the description fully enumerates what is returned, including field groups, ordering, caps, and error cases. It also covers young-fort degradation and the no-fort error, making it complete 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description adds no parameter details (none exist) but compensates by thoroughly describing the output context, making the tool's behavior unambiguous.
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 retrieving the loaded fort's permanent world saga entry, listing exact data types (founding info, name etymology, sieges, deaths). It distinguishes itself from the 'pruned live report stream' and sibling tools like chronicle by emphasizing durability 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the tool is scoped to the loaded site and contrasts the permanent saga with the live report stream, giving context on when to use it. It also notes error/degradation behavior for no fort or young forts, but stops short of explicitly naming alternative tools or exclusion criteria.
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 of explaining behavior. It thoroughly details what is returned, including the nuanced definition of citizenship and the time window for recent_deaths, and explicitly mentions the error case ('Returns {"error":"no fort loaded"}'). It does not explicitly state that it has no side effects, but the read-only nature is strongly implied.
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 and front-loaded with the core purpose. It is a bit long, but every sentence provides necessary detail, especially the elaborated recent_deaths semantics that would otherwise be unclear. No fluff or redundancy.
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?
There is no output schema, so the description must fully document return values. It covers all major fields (name, date, population, wealth, happiness, deaths, alerts) and goes deep on the trickiest attribute (recent_deaths), including the error condition. Given the tool's complexity, this is complete and self-contained.
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, and the schema is empty. The baseline for 0 params is 4. The description wisely allocates space to explaining the rich output instead of parameters, which adds no further semantic value needed.
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 phrase ('One-call situational overview') and lists the exact resources covered (fort name, date, population, wealth, happiness, deaths, alerts). It also distinguishes itself from sibling tools by explicitly calling out the murder/loyalty-cascade signal as unique ('which no other tool reports').
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 clearly frames when to use the tool ('One-call situational overview', 'pre-triaged list of alerts') and highlights the unique murder signal, implying this is the go-to for that specific need. However, it does not explicitly state exclusions or name alternative tools for deeper dives into individual areas (e.g., threats or fort_health).
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 burden. It discloses truncation behavior (*_truncated flags), the special handling of unbuilt restraints, and the error return when no fort is loaded. It also implies a read-only nature by describing it as a reporting tool, which is transparent for an 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 dense but not bloated; each sentence contributes information about a different data category or behavior. It could be better structured with bullet points, but as a single paragraph it is efficient and front-loaded with 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?
Given no output schema, the description thoroughly covers the returned data types and edge cases, including truncation flags and the error case. It lacks a sample JSON structure, but the level of detail is sufficient for a complex tool, making it fairly 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 schema carries no burden. The description adds no parameter details since none exist. Baseline 4 is appropriate for a parameterless tool.
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 enumerates the tool's specific content: production mandates, export bans, unmet room demands, and justice state. This distinguishes it from sibling tools like nobles_and_administrators or petitions by naming unique data groups. Although the opening sentence is a noun phrase, the rest explicitly states what is reported.
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 contextual guidance by stating what it does not cover ("not what to build about it") and where to find related info ("threshold restatements are in alerts"). It stops short of naming alternative tools, but the usage context is clear enough for the agent to decide when to invoke 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 clearly discloses error behavior ('returns error if no fort loaded', manifest_error/agreements_error for genuine bugs), and clarifies that manifest is before unloading. It does not explicitly state read-only/no-side-effects, though it is implied by the reporting nature.
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: it opens with an overview of the main report elements, then details each caravan's additional fields, explains error handling, and ends with the error return. No sentences are wasted; it is appropriately sized for the complexity.
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?
There is no output schema, so the description fully takes on the job of explaining return values. It covers not only the top-level state but also nested manifest and agreement structures, their distinct taxonomies, and failure modes. This is complete enough for an agent to know exactly what to expect.
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, and the schema reflects that with an empty properties object. Per the rubric, a baseline of 4 applies; the description need not add 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 is highly specific, enumerating the exact aspects of trade status it reports (depot existence/accessibility, caravan lifecycle, broker status, staged goods, manifests, agreements). It uses a clear verb 'Reports' and resource 'the trade picture', and the 'not what to trade' line distinguishes it from advisory 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?
The description gives clear context on what data is available, and explicitly includes a when-not ('not what to trade') exclusion. However, it does not name alternative sibling tools or state explicit conditions like 'use this when you need current caravan state'.
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 transparency burden. It discloses the return format, the namespace bias, and the HTTP-only nature. However, it does not explicitly state that the operation is read-only or has no side effects, though 'works without the game running' strongly implies it. This is a minor gap for a search 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 tightly composed of three sentences, each serving a distinct purpose: purpose, usage context, and technical details/return format. No verbose or redundant language is present.
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 low-complexity tool with one parameter and no output schema, the description covers all essential aspects: what it does, when to use it, constraints, and the exact return shape. The inclusion of result count and snippet details provides sufficient operational context without an output schema.
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 fully describes the single 'query' parameter (100% coverage). The description adds no new information about parameter syntax or semantics, merely restating that it searches. The baseline of 3 is appropriate given the schema's sufficiency.
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 searches the Dwarf Fortress wiki for candidate article titles and cleaned snippets. It also distinguishes itself from siblings by positioning as a discovery/disambiguation step before wiki_lookup, with a specific namespace bias.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative (wiki_lookup) and specifies this tool is a precondition for it. It also adds a practical constraint (pure HTTP, no game required) that helps the agent decide 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: READ-ONLY, availability (not behind actuator gate), member list cap at 200, member_count always full, members_truncated flag, and cursor-based pagination with members_cursor. This is comprehensive.
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 every sentence earns its place, explaining the output fields, truncation, and pagination. It is front-loaded with the core purpose but could perhaps be tightened without losing critical information.
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?
With no output schema, the description thoroughly explains the return facts (name, mode, labor tokens, assigned citizens), the pagination behavior, and the parameter semantics. It is self-sufficient for an agent to use the tool correctly.
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 100%, but the description adds significant meaning: the detail parameter is exact-match and returns only that detail, with example 'Miners'; members_after is a cursor tied to members_cursor from a truncated response. This elevates beyond 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 clearly states the tool's purpose with a specific verb ('List') and resource ('fort’s work details' / labor-management groups), and enumerates the output fields. It does not explicitly distinguish from sibling tools like jobs_and_labor, so it misses the top score.
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 usage context: it's READ-ONLY, always available, and serves as the readback sensor for assign_work_detail. It explains optional narrowing parameters and pagination, but does not explicitly say when to choose this over alternatives.
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 are provided, so the description carries the full burden. It discloses exact computation of tile_count (summed over assigned blocks, not bounding box), the 200-item cap on assigned_units with truncation flag, and the error case for no fort loaded. This is thorough and transparent for a read operation.
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 detailed and front-loaded with the core purpose, followed by field-by-field explanations and a brief note on the error response. While it is long, every sentence adds value given the lack of output schema and annotations. The parenthetical explanations are dense but informative, though slightly verbose.
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?
Given no annotations, no output schema, and zero parameters, the description is remarkably complete. It covers the return object's fields, the precise meaning of tile_count, the assignment cap behavior, the relationship with civilian_alert, and the error case. This leaves no significant gaps for an agent to understand the tool's function.
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 is 4. The description adds no parameter-specific semantics because there are none, but it fully explains the output structure which is the only relevant aspect for an agent invoking this tool.
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 it returns the fort's burrows as facts, enumerating specific fields (id, name, tile_count, assigned_units, civilian_alert_linked). It distinguishes itself from the civilian_alert tool by explaining that civilian_alert reports the alert's own state, while this tool provides burrow data. The verb is implicit but the resource and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use this tool versus civilian_alert, noting that civilian_alert reports the alert's own state and mentions it pairs with a toggling actuator. However, it doesn't explicitly state 'use this for burrow information' or provide exclusions. The relationship is implied rather than directly instructing the agent on 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?
With no annotations provided, the description carries the full burden of disclosing behavior. It thoroughly covers what the tool returns (social graph, deities, personality extremes, etc.), defines friends/grudges, notes placeholder caveats in thoughts, states empty categories degrade to [], and explicitly covers error responses for missing unit_id or no fort. It even clarifies 'Facts only — it senses, it does not advise.'
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 each sentence provides valuable detail, from data categories to error handling to placeholder behavior. It is front-loaded with the main purpose and uses a clear contrast with find_unit. While slightly verbose, it does not waste words and is well-organized.
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?
Given the absence of an output schema and annotations, the description does an excellent job of covering all necessary context. It enumerates the full set of returned categories, defines the semantics of friends/grudges, explains the placeholder issue, and states both error conditions. It fully equips an agent to decide when to call the tool and what to expect.
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 unit_id with pattern and description, so the baseline is 3. The description adds extra meaning by explaining where unit_id comes from ('find_unit or chronicle') and that it enables graph walking ('each with a unit_id you can pass back into citizen()'). This adds chaining semantics 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 states it provides 'a deep dossier on ONE citizen' and differentiates from the sibling tool by explicitly noting 'Where find_unit stays compact, this is the depth.' This identifies the tool's specific verb (provide a deep dossier) and resource (citizen), distinguishing it from 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?
The description explains the chaining context: 'chained by unit_id from find_unit (or chronicle)' and contrasts with find_unit. This provides clear context on when to use the tool, but it doesn't explicitly list exclusions or say 'don't use when you only need a compact summary.' The alternative is named, so it nearly meets the highest bar.
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 thoroughly explains fog-of-war gating, the exact distance metric (Chebyshev), the classification of inside/outside via walkability groups, and the per-z-level terrain view. It also discloses caveats about unlinked levers/bridges, undiscovered tiles as '?', and the exact error message when no fort is loaded.
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 every sentence adds unique, non-redundant information about distance calculations, terrain logic, and caveats. The opening sentence effectively front-loads the core purpose. It could be tightened by splitting into bullet points, but the density of new information justifies its length.
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?
Given the tool's complexity, empty schema, no annotations, and no output schema, the description is exceptionally complete. It covers all returned data categories, calculation methods, edge cases (e.g., no walkable footing), and the error condition. It leaves no significant behavioral aspect unexplained.
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 description correctly omits parameter details. The baseline for no params is 4, and the description adds no irrelevant parameter info. It confirms the schema's emptiness by focusing entirely on the output and behavior.
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 dual purpose: reporting active discovered hostiles with their geometry to fort structures, and listing controllable defensive structures. It distinguishes itself from siblings like threats() by explicitly comparing its hostiles count to threats()' active_hostiles and adding the defensive inventory. The verb 'returns' and concrete resources make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context, telling the agent to use identify() for creature trait facts (explicit alternative) and warning about fliers/buildings that may be reported 'outside' despite being a threat. It also notes limitations like single-z terrain, implicitly guiding when to cross-reference other tools. However, it doesn't explicitly say when to prefer this over threats() or military(), but the added defensive structures make the unique value clear.
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 burden and does so thoroughly: it discloses fog-of-war behavior (reports nothing about undiscovered cavern layers), error handling (returns error if no fort loaded), and build limitations (no savage flag). It also notes the payload is small and fixed-size, adding performance context.
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 dense paragraph that front-loads the main payload and uses clarifying asides. Every sentence adds value, but the length could be slightly reduced by breaking into bullet points or trimming redundant phrasing like 'Small fixed-size payload.' Still, it remains well within acceptable bounds.
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?
Given no output schema, the description must explain the return values and edge cases, which it does comprehensively: season, weather, temperature, freezing condition, biome alignment, cavern list, empty list behavior, and error response. It also addresses limitations like unavailable per-tile savagery, making the tool's behavior fully predictable.
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 schema provides no parameter semantics. The baseline for 0 params is 4, and the description compensates by explaining what the tool returns rather than parameter details, which is appropriate given the output-focused nature of the tool.
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 a read-only environmental status reporter, enumerating specific outputs (season, weather, temperature, freezing, biome alignments, cavern states). It distinguishes itself from siblings like geology and tile_region by focusing on ambient conditions and explicitly referencing geology's complementary fact.
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 (to check ambient conditions, frozen water, biome alignment, cavern accessibility) and even suggests composition with geology(). However, it does not explicitly state when not to use it or name alternative tools for cases like per-tile savagery, which is mentioned as unavailable.
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 burden and excels. It discloses how fields are computed (revealed-only, fog-of-war safe), caps (50 layers, 200 z-levels, 50 flood risk, 20 wells), special cases (frozen water disappears from water_layers, 'mixed' classification, magma sea threshold, flood risk as exposure not prediction), error handling ('no fort loaded'), and the scan.complete flag when the tile budget is hit. This is exceptionally transparent.
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 dense with information. Every sentence adds value: each field is explained with meanings, caps, and edge cases. It is structured as a single flowing paragraph, which could be improved with bullet points or section breaks for readability, but given the complexity, the length is justified and there is no fluff.
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?
With no output schema, the description is the sole source for return value semantics. It covers every field (aquifer_layers, water_layers, ice_layers, magma_sea, flood_risk_tiles, wells) in detail, including sub-field meanings, caps, and interactions. It also explains the scan.complete flag and error response, making it fully complete for an agent to understand what the tool returns and its limitations.
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 is 4 per the rubric. The description doesn't need to explain parameter semantics; it instead thoroughly describes the output fields, which is valuable but outside this dimension. No deduction needed.
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: 'Water and magma engineering facts the Earthworks tier (tile_region, geology) does not cover' and enumerates specific resources like aquifer layers, standing/flowing water, magma sea, flood exposure, and well depth. It distinguishes itself from sibling tools by explicitly naming what it covers beyond tile_region and geology.
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 sentence frames this as the complement to tile_region/geology, indicating when to use it (when you need water/magma engineering facts not covered by those). It also mentions 'Facts only — no dig/pump/floodgate recommendations' as an exclusion. However, it doesn't give explicit scenarios like 'use when planning flood defenses' or contrast with every alternative, but the guidance is clear and useful.
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 excels by explaining non-obvious behaviors: old wounds are never deleted and thus old_wounds_only dwarves are not casualties; sleepers are excluded from unconscious because they carry a nonzero unconscious counter; care_needs is empty when no care is required; and it returns an error if no fort is active. These details go far beyond the schema and provide crucial edge-case understanding.
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 paragraph but is tightly packed with necessary information. It starts with the main purpose, then defines each category, explains edge cases, and ends with the error condition. Every sentence adds value and there is no redundant or filler content. It is verbose but highly efficient for the complexity it covers.
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 the lack of output schema, the description must explain return values. It thoroughly explains the semantics of each field (wounded, old_wounds_only, patients, bedridden, unconscious, care_needs) and the error case, but it does not explicitly state the exact JSON structure (e.g., whether the fields are arrays of IDs or counts). This leaves a small gap, but the definitions strongly imply the format, so it is mostly complete. A 4 is appropriate.
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 input schema is empty and schema_description_coverage is 100%. No parameter explanation is needed from the description. The baseline for 0 params is 4, and the description does not need to compensate for anything. It appropriately does not mention parameters, which is acceptable.
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 it provides 'The fort's medical picture' with a focus on CURRENT condition rather than history. It specifically defines the resource and content, distinguishing it from any other medical-related siblings by enumerating unique categories like wounded, old_wounds_only, patients, etc. This is a specific verb+resource with clear scope.
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 you need the fort's current medical picture, with detailed definitions of what counts as wounded, patients, etc. It does not explicitly mention alternatives or exclusions, but the context is clear enough to infer the appropriate usage. A score of 4 is appropriate as it falls short of explicitly naming when not to use it or citing alternatives.
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 delivers robust behavioral disclosure. It details that cancellations count occurrences rather than collapsed report rows, mentions the retained buffer window, notes the exclusion of children/babies from the labor pool, and states the exact error response for a missing fort. This is exceptionally transparent.
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 information-dense but well-organized: a colon-led main clause introduces the workforce data, and a separate sentence covers cancellations and chronicle. Each sentence contributes unique value without redundancy, though the second sentence is quite long and packed with detail.
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?
In the absence of an output schema, the description sufficiently explains the return categories: workforce utilization, idle percentage, ranked job breakdown, and cancellations (with aggregation and time-window context). It also covers the error case, making the tool's behavior fully understandable without external documentation.
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 no parameters, so the schema is empty and there is nothing to explain. According to the rubric, a baseline of 4 applies for zero-parameter tools, and the description appropriately introduces no parameter-related claims.
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's main function: providing workforce utilization statistics (busy vs. idle), idle percentage, a ranked breakdown of jobs, and cancellation aggregations. It also explicitly distinguishes itself from the sibling tool 'chronicle' by contrasting aggregation behavior, so its purpose is unambiguous and differentiated.
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 gives interpretive guidance for high idle ('unassigned labor or nothing queued') and draws a comparison with chronicle to help choose between them. However, it does not explicitly mention alternatives like work_order_list or provide a broader when-to-use/not-use framework, so it falls short of a full 5.
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 thoroughly discloses behaviors: result caps (100 distinct combinations), fog-of-war gating, civ restriction, isActive/isDead requirements, and the error response when no fort is loaded. It even explains nuances like grazer status not being gated on adulthood and egg_layers counts being gated on adulthood. This fully compensates for the absence of annotations.
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 lengthy but dense with essential information for a tool with no output schema. It is front-loaded with the purpose and organized by field categories. While it could be broken into clearer sections, every sentence earns its place given the complexity and the need to document edge cases.
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?
The description is exceptionally complete for a tool with no output schema. It explains all major fields (tame_total, by_group, grazers, egg_layers, marked_for_slaughter, trained, cages, unassigned_count), their semantics, caps, and edge cases. It even covers error conditions, making it sufficient for an agent to use correctly without additional documentation.
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 is 4. The description cannot add parameter-level detail, but it thoroughly explains the output fields, which indirectly helps an agent understand what the tool returns. No parameter information is needed beyond the empty 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 defines the tool's purpose: 'The fort's tame animal economy as facts.' It distinguishes itself from siblings by stating that 'every prior tool sees hostiles (threats) or nothing at all here,' making it the definitive tool for tame animal data. The extensive field enumeration further clarifies 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 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 by noting that other tools either see hostiles or nothing here, implying this is the go-to for tame animal information. It also clarifies exclusions (e.g., caravan animals) and gates (fog-of-war), but does not explicitly name alternative tools for specific use cases beyond the initial distinction.
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 fully discloses behavior: it distinguishes physical lever orientation from linked gate state, details the structure of linked_targets and state strings, explains truncation caps and the always-true totals, and includes the error response for no fort. This is exceptionally transparent.
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 dense single paragraph, but every clause delivers necessary behavioral detail. It lacks visual structure like bullet points for scannability, but it front-loads the purpose and has no redundancy.
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 no output schema, no annotations, and zero parameters, the description is exceptionally complete. It covers all major output fields, state semantics, truncation behavior, and error handling, leaving little ambiguity for an AI agent.
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 input schema has zero parameters, so the baseline is 4. The description doesn't need to explain parameters and instead focuses on output structure, which is appropriate. No undocumented parameters need compensation.
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 presents the fort's lever/pressure-plate wiring as factual data, and it explicitly says 'levers[] lists every lever' and 'pressure_plates[] lists every plate's linked_targets'. This distinguishes it from sibling tools by focusing specifically on mechanisms, and it even notes its pairing with pull_lever.
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 players/AI forget which lever controls what, and before queueing a pull to check for pending jobs. However, it does not explicitly discuss when not to use it or name alternative tools for other fort information, so it lacks 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, the description carries the full burden and exceeds expectations. It discloses nuances such as roster excluding dead/off-map units, uniform aggregation logic (assigned vs missing), ammo target being a shared total not per-soldier, training schedule behavior, and an error response when no fort is loaded. This is extensive behavioral transparency.
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 verbose and presented as a single dense paragraph, which can be harder to scan. However, each sentence provides necessary detail and the length is justified by the complexity of the returned data. It is not maximally concise but is appropriately detailed.
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?
Given there is no output schema, the description fully specifies the return structure, including edge cases, error handling, and the meaning of each field. It covers all aspects of military data comprehensively, making it complete for an agent to use correctly.
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?
There are zero parameters, so the description does not need to add parameter semantics. According to the rubric, 0 parameters receives a baseline of 4, which is appropriate here since no further detail is required.
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 what the tool does: it returns the fort's military information, enumerating squads, enlisted dwarves, filled positions, readiness, roster details, uniforms, ammo, training, and alerts. It is specific to the military domain and the content distinguishes it from siblings like 'threats' or 'defenses' without needing explicit mention.
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 on what data is returned, making it obvious when to use the tool. However, it does not explicitly mention alternatives or exclusions, so it falls short of the highest rating. For example, it doesn't say 'for threats use threats tool'.
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. It thoroughly discloses edge cases (off-map holders lacking unit_id, expected vacancies via superseded_by), additional data (bookkeeper precision, election state, monarch arrival), and error behavior (returns error if no fort is loaded). This is exemplary transparency.
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 dense paragraph, but it covers a complex set of roles, semantics, and practical use cases. Each clause adds value, and the opening sentence clearly states the core purpose. While a bulleted list could improve scannability, the content is appropriately sized for the tool's richness.
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?
There is no output schema, so the description must fully explain return values. It does this comprehensively: the structure of facts, the meaning of histfig_id and unit_id, the bookkeeper precision scale, pending elections, monarch arrival, and the error response. It also covers common misinterpretations (vacant superseded_by is normal). Complete for a zero-parameter informational tool.
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 schema coverage is trivially 100% and there is nothing for the description to add at the parameter level. A baseline of 4 is appropriate for parameterless tools; the description's focus on output interpretation is more relevant and handled under other dimensions.
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 ('reports'), identifies the resource ('the fort's appointed positions'), and enumerates the exact role hierarchy, making it clearly distinct from sibling tools. It goes beyond a simple label by describing what facts are returned and how to interpret them.
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 ties vacancies to concrete validation problems: 'work_order_create needs a manager, trade needs a broker, mandates_and_justice punishments need a hammerer.' This gives strong contextual cues for when to query this tool. However, it does not explicitly discuss when not to use it or mention alternative sibling tools by name, falling just 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.
- Behavior5/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 so thoroughly. It discloses nuanced behaviors: bounding-box vs. real footprint, the exact meaning of barrels_allowed/max_bins (0 means no containers, not unlimited), the distinct reading of max_wheelbarrows, category omissions, item_count being positional and including container contents, occupied_tiles being a direct count not a percentage, and the error response. It even documents a discarded draft field as fabricated, demonstrating exceptional transparency.
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 clear summary and then systematically details each returned field in a logical order (piles[] fields, then fort-wide fields). It is long, but most sentences convey essential caveats or exact semantics. Some historical notes, like the dropped draft's placeholder constant, are slightly extraneous but still support transparency, so it earns a 4 rather than a 5.
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?
The tool has no output schema, so the description must explain the full return shape, and it does: every field is named with its type, meaning, and edge cases, plus the error condition. Fort-wide summaries, truncation flags, and exact counting rules are all covered, making the description self-sufficient for an agent to understand what the tool returns.
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 and the schema coverage is vacuously 100%, so there are no parameter semantics to document. Per the rubric, a zero-parameter tool receives a baseline of 4, and there is no additional parameter behavior to add.
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 defines the tool as returning 'the fort's hauling/logistics picture' with per-stockpile fact sheets plus fort-wide backlog data, which are distinct from what stockpile settings alone provide. It specifies exact fields and explicitly addresses a stated need ('the hauling backlog the issue asks for'), giving it a precise scope beyond the mere title.
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 when to use the tool: to inspect stockpile configurations and hauling backlog, especially loose-item backlog, rotting items outside stockpiles, and dump-flagged counts. It does not explicitly name sibling alternatives like hauling_routes or stocks, but it provides clear context for its purpose and notes what it uniquely surfaces ('signals stockpiles alone don't surface').
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 fully discloses behavioral details: estimation assumptions (2 food/5 drink per dwarf per season), the wear scale (4-stage), and the error response when no fort is loaded. It also explains the count of citizens with no shoes, adding context beyond a simple output 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 somewhat verbose, especially the detailed explanation of the wear scale, but every sentence serves a purpose in clarifying output. It front-loads the main purpose and then provides necessary assumptions and error handling, making it appropriately structured for the complexity.
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?
Given the zero parameters, no annotations, and no output schema, the description is remarkably complete. It covers all major return elements (food/drink, critical materials, stock lists, clothing) and error behavior, leaving little ambiguity for an agent.
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?
There are no parameters, so the baseline is 4. The description doesn't need to explain parameters, but it does add context about the output (days-of-supply, counts, clothing) that helps interpret the tool's behavior.
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 what the tool does: it reports food/drink days-of-supply, critical material counts, notably low/high stocks, and clothing wear status. It uses specific verbs and resources, and the focus on days-of-supply and worn clothing distinguishes it from siblings like 'stockpiles'.
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, such as monitoring food/drink supply, critical materials, and worn clothing as a stress source. It lacks explicit exclusions or alternatives, but the intended use cases are strongly implied.
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 full responsibility. It discloses READ-ONLY behavior, pagination limits (cap 256, truncated flag, next_cursor), and explains the validation state meaning, offering comprehensive behavioral transparency.
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 sentences, front-loaded with purpose, followed by necessary details on returned fields and pagination. While dense and efficient, the field list is long and could be more compact, but every sentence earns its place.
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?
Since there is no output schema, the description enumerates all returned fields, explains validation semantics, and covers pagination and availability. It's fully self-contained for an agent to understand what to expect and how to handle results.
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 describes after_id, and the description adds value by explaining the pagination flow (sorted by id, cap, next_cursor). This goes beyond the schema's bare parameter description, reinforcing usage context.
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 ('List'), names the resource ('fort's active manager (work) orders'), and enumerates the returned fields (id, job type, output tokens, amounts, etc.), making its purpose unambiguous and clearly distinct from siblings like work_details or jobs_and_labor.
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 states this is the readback sensor for work_order_create/_cancel and that it's always available, giving clear when-to-use context. It doesn't explicitly contrast with alternative tools, but the purpose is specific enough that use cases are well implied.
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 excels: it discloses pagination behavior ('Use limit + next_cursor'), scope-dependent counts ('artifact_count always reflects the scope actually applied'), conditional maker unit_id ('only when the maker is a living current citizen'), the critical limitation that art_images_loaded is false (subjects_resolvable=false), and the error response ('{"error":"no fort loaded"}'). This exceeds typical 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?
Although long, every sentence serves a purpose. It opens with a crisp summary, then systematically covers artifact fields, engraving aggregation, a critical precondition, pagination, and error handling. The structure is front-loaded with the core purpose and flows logically, with no redundant or filler content.
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?
Without an output schema, the description fully describes the return shape: artifact fields (name, type, material, value, quality, maker, decorations, inscriptions) and the engraving summary (grouped by subject, quality histogram, top engravers). It covers limitations, errors, and pagination. For a tool of this complexity, nothing essential is missing.
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 coverage is 100%, so baseline is 3. The description adds meaningful nuance beyond the schema: it explains the semantic difference between site and world scope ('in world scope each row carries site_local so the two are still distinguishable') and how artifact_count reflects scope. Pagination via cursor is also clarified ('Use limit + next_cursor to page through artifacts'). This is more than a token addition, earning a 4.
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 'The fort's art, as labeled facts' and immediately specifies 'Returns the named ARTIFACTS (paginated), SITE-SCOPED BY DEFAULT' plus 'an aggregated ENGRAVINGS summary'. This clearly names the resource (artifacts and engravings) and the verbs (returns, aggregated), making it fully distinguishable from sibling tools like site_history or map_overview.
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 guides scope selection: 'SITE-SCOPED BY DEFAULT — only artifacts belonging to the loaded fort, which is almost always what is meant by "our artifacts"' and 'Pass scope="world" for every artifact'. It also warns against relying on iconography: 'do not plan on describing what the fort's art depicts'. However, no alternative tools are named, so it stops short of the 'alternatives' bar for a 5.
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 burden and excels: it explains the meaning of worst_focus, the exact floor calculation (-16320 × need_level), that identical values are normal, how to compare against floors, and the error response when no fort is loaded. This prevents misinterpretation and is highly 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?
Although lengthy, every sentence is purposeful: it front-loads the purpose, then details necessary interpretation details (floors, clamps, comparative semantics), and ends with scope and error handling. The structure is logical and free of fluff.
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?
The tool is a read-only lookup with no inputs, no annotations, and no output schema. The description fully explains what is returned, how to interpret the numbers, and the error case, making it completely adequate for correct use.
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?
There are 0 parameters, so the schema is fully covered and description does not need to elaborate. The description provides abundant context about the return value semantics instead, which is the relevant behavioral information for this tool.
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 returns aggregate unmet needs across all citizens, with a specific verb ('Returns') and resource ('dwarven needs system'). It distinguishes itself from related tools by noting it complements fort_status happiness and explicitly says it reports which needs are unmet, not how to fix them.
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 context ('Why the fort is stressed') and clarifies that it complements fort_status happiness, but it does not explicitly name alternative tools or state when not to use it. It does say it reports unmet needs rather than fixes, implying its scope.
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 burden and delivers extensively. It discloses multi-hop redirect following, section fragment resolution, disk cache with 30-day TTL, refresh bypass, pure HTTP operation without the game, and the exact return payload shape including error case for not-found pages. This is exemplary 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 concise and front-loaded with the primary action, then layers in behavioral nuances in a logical order: redirects/fragments, caching, operational dependency, and return format. Every sentence carries distinct information with no redundancy or filler, achieving high information density in a compact form.
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?
Despite no output schema, the description fully specifies the return object and error behavior. It covers all major context needed to invoke the tool: article title, section scoping, cache behavior, and runtime independence. The tool's complexity is well-addressed, and it stands clearly apart from the sibling wiki_search tool.
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 provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema by explaining how refresh bypasses the cache and by giving a concrete example of section fragment resolution ('Weapon trap' to the Trap page section), which helps the agent understand the section parameter's behavior more intuitively.
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+resource: 'Fetch a Dwarf Fortress wiki article as clean, readable text,' clearly distinguishing this from the sibling tool wiki_search by focusing on retrieval of a specific article rather than search. It also specifies the DF2014 namespace scope, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: to get a clean-text version of a wiki article, with redirect and section handling, and works without the game running. It does not explicitly name alternatives or say 'use wiki_search instead for fuzzy lookups,' but the fetch-vs-search distinction is implicit and sufficient for an agent to choose correctly.
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 thoroughly discloses behavioral traits: the front-pruned window, stable ids, `pruned:true` flag, combat spam collapsing, and the rules about speaker_id and pos tile anchors. It even specifies the error response for no fort loaded, covering edge cases comprehensively.
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 every sentence contributes necessary information. It is front-loaded with the core purpose, then logically progresses through cursor usage, defaults, pruning, categories, combat spam handling, facts, and error handling. There is no redundancy or filler, making it appropriately concise for its complexity.
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?
Given the tool's complexity and lack of output schema, the description covers return semantics (cursor, pruned, collapsed), error handling, and parameter behavior. It preemptively answers likely questions about pagination, stale cursors, and combat-heavy stream summaries, making it contextually 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?
Although the schema already documents all parameters, the description adds significant context: default limit 50 and max 200, oldest-to-newest ordering, `since` semantics (id > since), and the pruned flag when `since` is stale. It also clarifies the `categories` filter with an exhaustive list of values.
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 reading the fort's announcement/report stream and specifies the event types (combat, deaths, moods, artifacts, sieges, migrants). It distinguishes itself from sibling tools by focusing on this unique stream with triaged, cursor-addressable events.
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 when to use the tool (to fetch announcements) and provides detailed usage instructions: passing `cursor` back as `since` for incremental fetches, omitting `since` for recent events, and using `categories` to filter. However, it does not explicitly mention when not to use it or compare it with alternatives, though the tool's unique scope makes this less critical.
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 fully carries behavioral disclosure. It explains that fps/gfps are current calculated values (not averages), item counts include all object states, unit counts are fog-of-war filtered and intentionally undercount, dead_on_map is specific, and the tool returns an error if no fort is active. This is exceptionally transparent.
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 dense but every sentence provides necessary detail, and it front-loads the core purpose. It is a single long paragraph, which could be better structured, but it is not bloated or redundant.
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?
Given no output schema, the description thoroughly explains all return fields (fps, gfps, items breakdowns, units splits) and even clarifies their meaning relative to other tools. It also covers edge cases (error, fog-of-war) and cross-references alternatives, making it fully complete for a zero-parameter tool.
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 and an empty input schema, so parameter semantics are not applicable; baseline 4 applies. The description instead focuses on output field semantics, which adds value 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 explicitly states the tool reports 'the fort's computational health as facts,' covering FPS, item counts, and unit counts. It differentiates itself from siblings by noting it's the only source for 'FPS death' and clarifying differences from stocks and livestock_and_pastures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it explains when to use this tool (for computational load, using raw item/unit counts) versus alternatives like stocks (for usable stock) and livestock_and_pastures (for unassigned_count). It also warns about fog-of-war undercounting and the error condition when no fort is loaded.
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 fully carries the transparency burden. It discloses default fog-of-war behavior, omission of undiscovered caverns and magma sea, the debug/spoiler nature of reveal_hidden, the error response when no fort is loaded, and clarifies that it reports what exists rather than digging directions. This is exceptionally transparent.
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 dense and long, but every clause adds unique value, such as the distinction between surface_z_max and surface_z_at_core, the meaning of permanent_freeze, and the format of layer stacks. It is front-loaded with a summary sentence and then systematically details outputs. The length is justified but could be made more scannable with bullet points.
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?
There is no output schema, so the description must explain return values entirely. It does so comprehensively, covering each output category, their formats, exclusions, error handling, and the effect of reveal_hidden. This makes the tool fully understandable without external documentation.
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 has 100% parameter coverage, so the baseline is 3. The description adds meaningful context by explaining the reveal_hidden parameter's bypass behavior, naming the returned fields (caverns_hidden, magma_hidden), and labeling it as a debug/spoiler switch. This goes beyond the schema's description, earning a 4.
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 it performs a geological survey of the embark and enumerates specific return values (surface_z_max, layer stack, aquifer, caverns, magma sea, surface water). It also distinguishes itself from map_overview by explicitly contrasting surface_z_max with surface_z_at_core, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/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 this tool versus alternatives, notably contrasting with map_overview and explaining how results can be fused with wiki_lookup and game_data. It also clarifies the default behavior and when the reveal_hidden parameter should be used, offering clear context for tool 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?
Despite no annotations, the description discloses critical behavioral traits: well truncation flag, aggregation of bedroom/coffin counts, ghost visibility rules (fog-of-war gated active[] vs world-flagged unquiet count), and the error condition when no fort is loaded. This goes well beyond minimal requirements.
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 every sentence carries substantive information about data categories or edge cases. It could benefit from bullet points, but the single-paragraph structure is acceptable given the tool's complexity and the need to explain nuanced behavior.
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?
With no annotations and no output schema, the description must carry the full burden, and it does. It covers all data categories, explains the ghost counting logic in depth, notes truncation, and specifies the error case. It is fully self-contained.
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 is 4. The description thoroughly explains what the output contains, which is the main semantic burden; no parameter descriptions are needed.
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 the fort's facility inventory with specific categories (bedrooms, dining halls, hospital, wells, temples, etc.) and explicitly positions it as the supply-side companion to unmet_needs(), distinguishing it from that sibling. The scope is precise and detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the companion tool unmet_needs() and clarifies that it 'Reports what the fort has, not what to build', providing clear when-to-use and what-not-to-use guidance. This directly helps an agent choose between alternatives.
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?
Given no annotations, the description fully carries the burden and excels: it discloses the clamp at 100x100 with truncated:true, the separate sparse liquids list, fog-of-war tiles never painted over, the self-describing legend, and the 'no fort loaded' error. It also clarifies that the grid is depth-blind. This is far more than typical 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 long but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers glyphs, liquid data, fog of war, optional parameters, clamping behavior, facts-only nature, read-only status, and error handling. There is no fluff or redundancy; the density is justified by the tool's complexity.
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?
With no output schema and no annotations, the description must explain return values and edge cases. It does: it describes the legend, the grid contents, the liquids list, the truncated/requested fields, the default window, and the error case. The description offers a complete mental model for an agent to use the tool safely and effectively.
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?
Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains that all parameters are optional, what the default 60x40 window is, how passing z alone recenters on that level's centroid, and how an oversized request is clamped. This enriches the parameter semantics significantly, making it worthy of a 5.
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+resource: 'A bounded window of ONE z-level rendered as an ASCII character grid plus a self-describing legend.' This clearly distinguishes it from sibling tools like map_overview or environment, and it goes on to enumerate exactly what is rendered and what classes of buildings are shown.
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 on when to use the tool, including default behavior with no parameters, optional z-level focusing, and explicit rectangle selection. It also states exclusions: it is read-only, facts-only, never suggests layouts, and never shows per-building detail. However, it does not name alternative tools or directly contrast with them, stopping short of the explicit alternatives guidance needed for a 5.
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 burden and excels: it discloses seed exclusions (forbidden/dumped/rotten/trader-bound), caps (100 plants, 200 plots), truncation flags, the open_to_sky clarification, and the relationship between no_crop_assigned and no_eligible_crop. It even notes the error response when no fort is loaded.
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?
Though long, the description is dense with essential information and structured logically: purpose first, then plot fields, flags, seed totals, caps, and error. Every sentence earns its place, making it appropriately sized for the complexity.
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?
Given the complex output structure and no output schema, the description fully explains the return values: plot dimensions, open_to_sky semantics, seasonal crop assignments, eligibility flags, seed count aggregation, caps, and error conditions. It also situates itself among siblings, making it complete for an agent.
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 and empty schema, so the baseline is 4. No parameter information is needed, and the description does not attempt to fabricate any. It instead adds valuable semantics about the output data model, which is a bonus.
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 returns farm plots and seed stock, and explicitly distinguishes it from sibling tools: 'stocks (food OUTPUTS) and game_data (what is plantable, in the abstract) don't cover.' This is a specific verb+resource with clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool vs alternatives by noting what it covers that stocks and game_data don't. It also designates seed_totals as 'the single source for seed stock' and warns against using per-plot seed counts, giving clear usage direction.
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?
Without annotations, the description carries the full burden. It discloses return values (dossier, flags, attacks, interactions, wiki excerpts), how procedural creatures are handled, disambiguation behavior, and error behavior ('no game loaded'). It even decodes a flag example, providing rich context beyond a mere operational 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 well-structured: a one-line summary, then input forms, output explanation, edge cases, and an explicit alternative. Every sentence adds useful information without padding. It is appropriately detailed for the tool's complexity.
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?
Given no output schema and no annotations, the description adequately covers the tool's purpose, parameters, return values, edge cases, and comparison to alternatives. It is complete enough for an agent to select and invoke the tool correctly in a variety of scenarios.
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 coverage is 100% for the single 'query' parameter, so the baseline is 3. The description adds value by explaining the accepted forms (token, name, unit_id) with concrete examples and linking the contract to game_data, enhancing the schema's description without being redundant.
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 a specific verb+resource: 'fuses THIS WORLD's raws with the DF wiki' to identify creatures and provide handling strategies. It also distinguishes from siblings by explicitly saying 'Use this instead of a bare wiki lookup' and referencing game_data as a separate contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: what inputs to pass (creature token, name, unit_id), when to prefer this tool over a bare wiki lookup, and what to expect in cases of multiple matches or no game loaded. It directly names an alternative ('wiki lookup') and explains why this tool is better.
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 fully discloses behaviors: 'Cheap' (performance), 'fixed-size payload regardless of fort size', stair columns 'RANKED BY HEIGHT' then capped with truncation flag and total count, fog-of-war honesty ('undiscovered tiles never leak'), and the exact error response when no fort is loaded. This is exceptionally 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 dense but every sentence carries critical semantic weight, explaining nuanced edge cases (surface_z vs geology, helical shaft splitting, cap ordering, fog-of-war). It uses structured lists and parentheticals effectively, staying organized despite the detail. No filler or repetition.
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?
With no output schema provided, the description must explain all return values, and it does comprehensively: extents, centroid, surface_z_at_core (with null case), activity z-levels, stair columns (with ranking/truncation metadata), and error behavior. It also covers performance and honesty characteristics, making the tool fully understandable without additional documentation.
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 there is no schema to clarify. The baseline for 0-param tools is 4, and the description correctly omits parameter details since none exist. The behavior descriptions are entirely self-contained for a parameterless tool.
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 immediately states the tool's specific purpose: 'Cheap spatial orientation to run BEFORE any per-tile terrain read.' It enumerates exact outputs (map extents, fort-core coordinate, surface_z_at_core, activity z-levels, stairways) and explicitly distinguishes itself from sibling tools like geology() and defenses(), making its role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'run BEFORE any per-tile terrain read' and 'Use it to decide which z-levels and area to pull grids for.' It also clearly contrasts with geology()'s surface_z_max, warning against confusion and telling the user to 'pick the one you mean.' This gives both when-to-use and when-not-to-use context.
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 thoroughly explains output semantics: the meaning of warned_ready, deadline_days, status derivation from flags, truncation at 50 items with *_truncated flags, and the error response when no fort is loaded. This is exemplary transparency, exceeding what annotations would likely provide.
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?
Though the description is long, every sentence is informative and necessary. It is front-loaded with the core purpose, then methodically covers field semantics, associations, limits, and errors. The structure flows logically from general to specific, and there is no redundancy or filler. It is appropriately sized for the complexity of the tool.
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?
Given the extensive data model (two petition types, many fields, derived statuses, truncation flags) and the absence of an output schema, the description is remarkably complete. It explains not only what is returned but also how to interpret edge cases (e.g., warned_ready true with outstanding status, null deadlines, truncated lists). It also contextualizes the tool within the fort's broader analysis, mentioning the relationship to rooms_and_zones. Nothing essential is missing.
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 description cannot add parameter-specific meaning. The baseline for 0 parameters is 4, and the description does not need to explain parameters. It does, however, provide extensive detail about the returned data, which is more than expected. There is no gap in this area.
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: to list the fort's outstanding agreements as facts, specifically location petitions and residency/citizenship petitions. It uses specific verbs and resources ('location petitions', 'residency/citizenship petitions') and distinguishes itself from the sibling tool rooms_and_zones by explicitly noting the difference in how needs are tracked. This is far beyond a vague restatement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions the tool relative to rooms_and_zones, stating they are complementary and should be composed rather than expecting either to duplicate the other. It also provides context on when this tool is relevant (actual agreements tracked by DF vs inferred needs). This gives clear guidance on when to use this tool vs alternatives, and even flags the classic silent-failure case.
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 burden, and it excels: it discloses case-insensitivity, matching against either field, the exact return fields (profession, age, stress level, etc.), the error condition ('no fort loaded'), and the linkage to unit_id for further lookups. No behavioral trait is left unclear.
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 four sentences long, but every sentence carries unique information: purpose, return contents, usage examples, next-step guidance, and error behavior. It is front-loaded with the core action and stays dense without fluff.
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?
No output schema exists, so the description compensates by enumerating all return fields and their semantics. It also covers error behavior and provides a clear path to deeper investigation, making it fully self-contained for this low-complexity tool.
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?
Although the schema describes the query parameter as 'Name fragment or profession to search for', the description adds critical semantics: case-insensitive, matches either field, and provides example queries. This significantly enriches the parameter's 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 a specific verb ('Look up') and resource ('citizens'), and specifies matching by name fragment or profession. It clearly distinguishes itself from the sibling tool 'citizen' by noting that deep dossiers require passing the unit_id to citizen().
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage examples ('how is the chief medical dwarf' or 'find Urist') illustrate when to use this tool. It also provides an explicit alternative: use citizen() for a deep dossier, giving clear when-to-use versus when-not-to-use 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?
With no annotations, the description carries full burden and meets it: it discloses return behavior for single vs multiple vs zero matches, specifies the disambiguation behavior, and mentions the error response. It also clarifies the source semantics ('ground truth for THIS world') and that results are 'curated, labeled facts'.
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 purpose, then systematically builds detail: source contrast, kind coverage, query types, return outcomes, and error case. Every sentence earns its place; no filler or redundancy. The length is justified by the tool's complexity.
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?
The description is complete for a tool with two params and no output schema: it explains what the tool searches, how to construct queries, what the response shapes will be (dossier, disambiguation list, empty match), and error behavior. Nothing essential is left ambiguous.
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?
Although schema coverage is 100%, the description adds significant meaning beyond the schema: it explains the `kind` filter with a default value and enumerates the six kinds, and provides rich examples for `query` (tokens, substrings, and unit_id for creatures). This goes well beyond the schema's terse 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 clearly states a specific verb ('Look up') and resource ('the LOADED WORLD's raws'), and distinguishes from sibling tools by positioning itself as the authoritative source for procedural creatures that never appear on the wiki. It also lists the exact kinds of data covered, making the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with the wiki ('procedural creatures ... that never appear on the wiki'), indicating when to prefer this tool. It also provides concrete query examples and notes the default kind, giving clear guidance on how to use it. The error condition for no loaded game is also stated.
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/alexanderolvera/dfhack-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server