MrJ-JMRI-MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.2.0
Disambiguation5/5
Each tool targets a specific, well-defined operation with extensive descriptions that clearly distinguish it from others. Overlaps are minimal and explicitly disambiguated (e.g., stop vs emergency_stop vs park_locomotive). The consistent use of detailed docstrings ensures an agent can reliably select the correct tool.
Naming Consistency4/5
The majority of tools follow a verb_noun pattern (e.g., list_roster, set_speed), with a few exceptions like lights_on, layout_status, and night_mode that deviate. The naming is readable and predictable, but the handful of outliers prevent a perfect score.
Tool Count2/5
With 52 tools, the server far exceeds the typical 3-15 range for a well-scoped service. While the domain is broad and the tools are individually justified, the sheer number can overwhelm an agent, increasing the risk of misselection and decision complexity. A more focused set would improve usability.
Completeness5/5
The tool surface comprehensively covers all major aspects of model railroad control via JMRI: power, locomotives (throttle, speed, direction, functions, lighting, preparation/parking), turnouts, layout lights, sensors, signals, blocks, session management, safety modes, and status reporting. No obvious gaps exist for the stated purpose.
Average 4.8/5 across 52 of 52 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 108 commits in the last 12 weeks
- Last stable release on August 1, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under AGPL 3.0.
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.json to 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?
With no annotations provided, the description carries the burden of disclosing safety. It explicitly states 'No side effects' and explains that 'lit' is reported as a bool independent of aspect. This adds useful behavioral context beyond the tool's basic function, though it does not cover error handling or return format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, starting with the main purpose, then parameter details, and an additional note. Every sentence provides value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the essential information: what it returns (aspect and lit) and that it has no side effects. Minor gaps include lack of error handling or unique-match behavior, but overall it is sufficiently complete for a basic getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does so effectively by explaining the 'name' parameter: 'Mast name (system name or userName) or unambiguous fragment. Case-insensitive.' This adds significant meaning beyond the schema's bare 'Name' title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the current aspect of one signal mast.' This is a specific verb+resource pairing and distinguishes it from sibling tools like list_signals (listing all signals) and set_signal (changing an aspect).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to read a single signal's aspect) but does not explicitly mention alternatives or provide exclusions. It lacks guidance such as 'use list_signals for multiple masts' or 'use set_signal to change aspect.'
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?
Discloses that it 're-delivers the same standing restriction instruction as enter_exhibition_mode for whichever state is current', which adds behavioral context beyond the empty input schema. No annotations present, so description carries the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. Front-loaded with the core purpose, followed by usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple boolean report tool, the description is mostly complete. It does not specify the output format, but given the tool's simplicity, this is a minor gap. No output schema exists to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so input schema coverage is 100%. Description redundantly states 'No arguments.' but adds meaningful context about the tool's purpose, which is sufficient for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Report whether exhibition mode is currently on.' It clearly identifies the verb (report) and resource (exhibition mode status), and distinguishes from sibling tools like enter_exhibition_mode and exit_exhibition_mode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies when to call: 'if you're unsure whether it's still active (e.g. at the start of a new turn after a long gap)'. Provides context for usage but does not explicitly state when not to use or list alternatives.
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, description carries full burden. It discloses the underlying set_function call, the F0 convention (not guarantee), and same auto-acquire/no-op-safe behavior. Lacks explicit mention of prerequisites like requiring an acquired throttle, but overall provides substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with no filler. Front-loaded with primary action, then adds usage distinction. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description covers purpose, usage guidance, and domain context (F0 convention). Minor gaps in error handling or prerequisites, but sufficient for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter 'address' is self-explanatory; schema coverage is 0%, so description adds some context (locomotive address, DCC convention) but no format or range. It does not fully compensate for lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Turn on a locomotive's headlight(s)' with specific verb and resource. It distinguishes from sibling tools like set_function (by calling it a shortcut) and set_light (for layout lighting). The mention of F0 convention adds precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: on a plain 'turn the lights on' voice request without asking for function number. Also states when not to use: for layout/scenery lighting, use set_light. References auto-acquire and no-op-safe behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool auto-acquires the throttle if needed, validates the function locally, and is safe to call repeatedly due to JMRI's silent no-op and a local cache kept fresh by broadcasts. This provides good behavioral context, though it could mention potential side effects like sending commands to JMRI.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs and bullet-like separations for each parameter. It is informative without being overly verbose, though it could be slightly more concise by removing redundant phrasing like 'kept fresh by JMRI's own broadcasts from ANY client holding this address'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are 3 parameters, no output schema, and no annotations, the description is remarkably complete. It covers purpose, usage guidelines, behavioral traits (auto-acquire, local validation, idempotency), parameter semantics (including cross-references to sibling tools), and caching behavior. This is 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must and does add meaning. It explains that address auto-acquires the throttle, that function is validated locally and its meaning is decoder-specific, and that state is a boolean. It also adds context about function labels and the cache, which goes beyond the schema's bare definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: turning a locomotive's decoder functions (F0-F28) on or off. It distinguishes itself from siblings like lights_on/lights_off by noting that F0 is almost always headlights and that other functions vary per decoder. It also cross-references get_locomotive_functions for user-set labels, providing 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: if a user names a function by effect, call get_locomotive_functions first; only ask for the F-number if no label matches. It also states that out-of-range function numbers return an error without contacting JMRI. While it doesn't explicitly list when not to use the tool, the context is clear enough.
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?
Explicitly states 'No side effects', and clarifies it deals with layout lights, not locomotive headlights. With no annotations, this provides good insight into behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each adding distinct value: purpose, clarification, usage, and behavior. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what, why, when, and side effects comprehensively for a simple list tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, so description adds value by specifying it returns all lights with current state. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every JMRI layout light with its ON/OFF state, distinguishing it from locomotive headlight controls and sibling tools like get_light and set_light.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises use before get_light/set_light for discovery and answers 'what lights are there?'. Contrasts with locomotive headlight, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a key nuance: the operation depends on the mast's 'can be unlit' setting, and JMRI accepting 'lit' does not guarantee unlit capability. This goes beyond basic schema and provides valuable context about potential failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: it leads with the purpose, then the argument semantics, and ends with a critical caveat. Every sentence provides valuable information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the core purpose, parameter details, and a critical limitation. It does not describe return values, but these are not specified in any output schema. It could be considered slightly incomplete regarding what a successful result looks like, but overall it is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'name' as a string. The description compensates thoroughly with schema coverage at 0%, explaining that the name can be a system name, userName, or an unambiguous fragment, and that it is case-insensitive. This is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Darken a signal mast' with a specific verb and resource, and explicitly identifies the tool as a 'shortcut for set_signal(name, "off")', distinguishing it from the more general sibling tool set_signal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It presents the tool as a shortcut, implying it should be used for quickly darkening a signal mast instead of invoking set_signal with the 'off' argument. It also warns about the dependency on the 'can be unlit' setting. However, it does not explicitly discuss when not to use it or contrast with other alternatives beyond set_signal.
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?
Thoroughly discloses that it only affects lights, not speed, direction, throttle, track power, or signals, and describes the return value structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
All sentences are relevant and well-organized, though the description could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description covers purpose, behavior, exclusions, and return format completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline 4 applies; description doesn't need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool turns off every layout light and locomotive lights, distinguishing it from night_mode and other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it's the inverse of night_mode and provides example phrases, but could more explicitly contrast with single-light tools like lights_off.
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?
No annotations, so description covers behavior: case-insensitive, accent-insensitive matching, exact/partial, error handling on no/match ambiguity. Mentions it includes fields from list_roster. Lacks mention of performance or side effects, but none expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: opens with purpose, then usage context, then detailed behavior. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains it returns address on success and error details on failure. Mentions it has same fields as list_roster. Could be clearer on exact output structure, but sufficient for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'name' with 0% schema coverage. Description clarifies it's the spoken/typed name, explains matching tolerance, and indicates it resolves to address. This compensates well for lack of schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'resolve' and resource 'locomotive name to DCC address', distinct from sibling tools like acquire_throttle or set_speed which use the address.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when user names a locomotive instead of providing address. Directs to call this first, then pass address to other tools. Also explains behavior on ambiguous/non-matches: return error without guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden for behavioral disclosure. It explains that executor mode is ON by default and that calling the tool re-delivers the same standing instruction. This provides useful behavioral context beyond a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but slightly wordy. It front-loads the purpose and provides useful context, but could be more concise while retaining essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description covers purpose, usage context, and behavioral details comprehensively. It leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the description adds no further parameter info beyond the schema. According to the rubric, 0 parameters defaults to baseline 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports whether executor mode is on, using a specific verb and resource. It distinguishes from the sibling tool set_executor_mode by focusing on reporting rather than setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use the tool (e.g., at the start of a new turn after a long gap, or after user asked for more explanation) and explains that it re-delivers the standing instruction. It gives clear context for invocation.
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?
Discloses that the tool has no side effects, explains parameter semantics (system name or label fragment, case-insensitive), and clarifies the scope (layout light vs. locomotive headlight). Without annotations, this is detailed enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using separate paragraphs for parameter details and usage guidance. Slightly verbose but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description covers purpose, parameter semantics, side effects, and distinguishes from a related tool. Adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema only provides type and title for 'name'; description adds concrete examples (IL1, Depot Lighting), mentions acceptability of fragments, and case-insensitivity. This significantly enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the current ON/OFF state of one layout light,' providing a specific verb and resource. It also distinguishes from locomotive headlight queries, aiding in tool selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when not to use this tool and provides an alternative: 'for "is the Autorail's headlight on", use get_locomotive_functions instead.'
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?
No annotations provided, but description discloses that only labeled functions are returned, empty dict is normal, and slots F0-F28 exist. Explains behavior beyond a simple listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is informative and well-structured with paragraphs, but slightly verbose. Front-loads purpose. Detail is mostly justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input (fuzzy name), output (dict of labels, empty ok), and usage context (before set_function). No output schema but explains return format adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'name'; description adds that it's fuzzy-resolved same as find_locomotive and no need to call find_locomotive first. Schema coverage is 0%, but description adds significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a locomotive's named decoder functions, with an example. It distinguishes itself from siblings by noting it should be called before set_function when the user refers to a function by label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: call this before set_function when user refers to function by action, and if empty dict, ask for F-number as alternative. Tells when to use and what to do with results.
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 provided, but description discloses auto-acquire and no-op-safe behavior, referencing set_function's behavior, which is crucial for agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: one for core purpose, two for behavioral context and alternatives. No redundancy, efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, alternatives, and behavioral traits, but lacks return value description or error conditions. However, for a command-like tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter is 'address', which is not elaborated beyond schema. Schema has 0% coverage, so description should compensate, but it does not. However, 'address' is a standard concept in this domain, making it moderately clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it turns off a locomotive's headlight(s) and explicitly contrasts with layout/scenery lighting, differentiating from set_light.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this (locomotive headlight), when not (layout lighting), and references lights_on for additional context about F0.
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 provided, so the description fully discloses behavior: it states 'Read-only, no side effects' and details the returned fields (state, sensor, value, length, curvature, speed, comment), giving the agent full 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and informative but slightly verbose. It could be trimmed slightly, but every sentence adds context. It front-loads the primary function and then explains details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully explains what the tool returns, including the semantics of blocks and their attributes. It also covers use cases and contrasts with sensors, making it complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100% (empty schema). The description does not need to add parameter info. Baseline 3 is appropriate since the tool has no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists every layout block with occupancy state, and explicitly distinguishes from get_block. The verb 'list' and resource 'blocks' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does 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: 'Use this to discover what blocks exist before calling get_block' and answers specific questions like 'what blocks are there?' and 'is anything occupied right now?', contrasting with sensor-level queries.
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?
No annotations, but description details the write operation, re-reading state, and honest reporting of confirmation. Lacks mention of error handling or prerequisites, but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear first sentence, args section, and behavioral notes. Slightly verbose but all content is valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations or output schema, the description covers purpose, usage, parameters, and behavioral nuance. Could mention error scenarios, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema only provides names and types; description adds format, case-insensitivity, name matching via fragment, and explicit meaning of boolean values. Greatly enhances schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool turns layout lights ON/OFF and distinguishes from locomotive headlight functions, specifically mentioning sibling tools like set_function and lights_on/lights_off.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (for layout lights) and when not to use (for locomotive lights), directing to alternatives. Also explains the write-and-re-read behavior.
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?
Explicitly states 'No side effects — this only reads state, it never changes power.' Also explains returned name format and how to interpret it, providing full 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Args section, each sentence adds value, though slightly verbose. Could be tightened but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all needed aspects for a read tool: input parameter, no side effects, return values, and even guidance on how to answer user questions about system purpose. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter with no description; description fully explains its usage: system name, prefix, or fragment, case-insensitive, and default behavior when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the current power state (ON/OFF/UNKNOWN/IDLE) of one DCC system.' Verb+resource is specific, and it distinguishes from siblings like set_power, power_off_all, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (to read power state) and how to specify system with examples and default behavior. Does not explicitly state when not to use, but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses read-only behavior, no side effects, and that sensors reflect hardware. However, it does not mention error handling (e.g., if sensor not found) or return format details, which would enhance 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it starts with the core purpose, provides usage examples, and ends with behavioral notes. Every sentence adds value; no redundant or excessive text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the main return (ACTIVE/INACTIVE state) but does not specify the exact format (e.g., string, object) or potential errors. For a simple tool, it covers essential context but could be more explicit about the return representation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates. It explains the 'name' parameter with acceptable formats (system name, user label, or fragment), case-insensitivity, and examples, making the parameter's usage crystal clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the ACTIVE/INACTIVE state of a sensor, with examples like 'is block X occupied?'. It distinguishes from siblings by emphasizing there is no set_sensor tool, and it references the sensor's hardware-driven nature, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (to answer real-world state questions) and that it is read-only with no side effects. It also notes the absence of a set_sensor tool, guiding the agent not to look for one. This provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. States 'No side effects' and explains naming conventions (e.g., 'zou (test)'). Could mention if systems might be missing or dynamic, but overall transparent for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences. First states main action, second gives usage context, third explains naming. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, description is complete. Explains what each system's name means and that user sets them. Also mentions current power state. Sufficient for agent to understand tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline per instructions is 4. Description doesn't need to add param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List every DCC power system known to JMRI, with its current power state.' Uses specific verb 'list' and resource 'power system'. Differentiates from sibling tools like get_power and set_power by emphasizing discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use this to discover what systems exist before calling get_power' and 'to answer "what systems are there?"' Also notes 'No side effects.' Provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes that it loops server-side, returns success/failure lists, and catch-and-continue behavior. No annotations provided, so description carries full burden. Could mention potential side effects (e.g., lights are changed), but overall 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then args, then context, then return value. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavior, and return format. Could mention if any lights are not controllable, but completeness is high for a simple boolean tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter turn_on is fully explained: 'True to turn every layout light ON, False to turn every layout light OFF.' Schema coverage is 0%, so description compensates completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Turn EVERY layout light ON or OFF at once (depot, street, signal lamps — JMRI Light objects)'. Specific verb-resource-scope combination, and distinguishes from sibling tools like set_loco_lights and set_all_locos_lights.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (lighting request not naming a locomotive) and when not to (if request names a locomotive, use set_loco_lights or set_all_locos_lights). Also advises against using set_light in a loop.
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 discloses that it writes to JMRI, checks current state before sending, re-reads after 1 second for confirmation, the possibility of false confirmed, the bug with re-POSTing, exhibition mode behavior, and potential outdated JMRI version issues. This 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs for arguments, behavior, safe calling, and exhibition mode. While every sentence adds value, it is slightly verbose. However, the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters and no output schema, the description covers behavior, edge cases (exhibition mode, JMRI bug), error conditions (outdated version), and the nature of the return (confirmed flag). It is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds significant meaning: for 'system', it explains it can be a name, prefix, or fragment, is case-insensitive, and can be omitted for default. For 'turn_on', it clarifies True/False meanings. This exceeds what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Turn a DCC system's power ON or OFF, and report the state actually observed.' This is a specific verb+resource combination. It distinguishes itself from siblings like get_power (read-only) and power_off_all/power_on_all (apply to all systems).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does 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 control power for a specific system) and notes special cases like exhibition mode where turn_on=True is refused. It also mentions safe repeated calling. However, it does not explicitly exclude usage when other tools like power_off_all might be more appropriate.
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?
Discloses key behavioral traits: direction flip ramps to 0 first, auto-stop for hold_seconds, short vs long duration behavior, exhibition mode override, speed_percent relative to loco's max. No annotations provided, so description carries full burden. Still thorough, though missing error handling or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections for each parameter and behavior. Front-loaded purpose. Somewhat verbose but necessary for the complex behavior. Efficient use of sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return values for both short and long duration paths. Covers exhibition mode, auto-acquire throttle, and all parameter interactions. Complete for a tool with 6 parameters and complex behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully. It explains the negative sign shorthand for speed_percent, interaction between direction and negative sign, rampup/rampdown_seconds behavior in various scenarios, and hold_seconds auto-stop. Adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Change a locomotive's speed gradually — a smooth ramp up and/or down.' It specifies the verb (change), resource (locomotive speed), and distinguishes from siblings like set_speed and emergency_stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool over alternatives: 'Use instead of plain set_speed for "en douceur"/"progressivement" or a duration before stopping. Use emergency_stop for a panic stop — never sent here, even at rampdown_seconds=0.' Clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It states that the tool writes to JMRI, moves physical hardware, re-reads state after command, and warns about possible feedback sensor issues where 'confirmed' may be false. It also clarifies JMRI terminology for the boolean parameter, preventing ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear header and 'Args:' section. Every sentence adds value—no fluff. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (write with feedback), the description covers the command, parameters, and behavioral consequences. It mentions the 'confirmed' field but does not explicitly outline the return structure; however, since no output schema is provided, this is acceptable. A slightly more explicit statement about the output format would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only names and types. The description adds significant meaning: 'name' can be system name or user label (case-insensitive), and 'thrown' is explained with JMRI terminology ('THROW' vs 'CLOSE') and disambiguation from track terminology. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set a turnout CLOSED or THROWN, and report the state actually observed.' It specifies the resource (turnout) and the two possible states. This distinguishes it from siblings like get_turnout (read-only) and set_all_turnouts (sets all turnouts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to set a turnout to a specific state) and provides important context about feedback sensors and the 'confirmed' field. However, it does not explicitly contrast with alternatives (e.g., when to use get_turnout instead) or state when not to use. Still, the context 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: auto-acquires throttle if needed, JMRI ignores redundant requests, and a local speed cache keeps correct current speed. It lacks detail on potential side effects, but the main safety aspects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: core action, parameter explanation, usage contrast, and safety notes. Each sentence serves a purpose with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description fully covers purpose, usage context, parameter meaning, behavioral nuances, and safe repeated invocation. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'address' has 0% schema description coverage, but the description adds meaning: 'DCC address. Auto-acquires the throttle if needed.' This provides context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bring a locomotive to a controlled stop (speed 0%)'. It uses a specific verb and resource, and distinguishes itself from the sibling tool 'emergency_stop' by contrasting normal vs. panic stops.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool ('normal, intentional halt') versus when not to (panic/safety stop, use emergency_stop). Also notes it is safe to call repeatedly, even when already stopped.
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?
States 'No side effects', which is important for a diagnostics tool. No annotations are provided, so the description carries full burden; it adequately covers the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three sentences front-load the purpose, then give usage guidance and behavioral note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description fully covers the tool's purpose, usage, and behavior. It is complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a one-call diagnostic that checks if JMRI is reachable and reports its version and power system states. It distinguishes itself from siblings by being the first tool to call when something isn't responding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call this tool first when something isn't responding, rather than guessing which tool to retry, providing clear usage 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?
No annotations provided, but description fully discloses behavior: sends same e-stop as emergency_stop to each acquired address, return format, and safe handling of already-stopped locos. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold emphasis, clear sections, and efficient sentences. Slightly long but all content earns its place; minor multilingual phrases ('arrête tout') add minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, description covers purpose, use context, limitations, behavior, return format, and distinctions from siblings. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, schema coverage 100%. Baseline for 0 params is 4. Description adds no param info (unnecessary), but confirms no arguments needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Emergency-stop EVERY locomotive currently under this session's control at once.' It clearly distinguishes from siblings like emergency_stop (single address) and power_off_all (track power cut).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (panic button, no time for individual locos) and when not (power cut). Provides clear alternative: power_off_all for full guarantee. Limitations explained (only session-acquired locos).
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 provided, so description carries full burden. It details password comparison tolerance, that it's a casual demo guard not real auth, success effects (restores speeds, reverse, power, DCC address), and failure behavior (leaves mode ON, returns instruction). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with purpose first, then password details, then usage guidelines. However, it includes some redundancy (e.g., 'restoring full normal control' and later 'restores real speeds...'). Minor improvements could make it more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description hints at return behavior (instruction on failure). Covers success and failure outcomes. Could mention side effects on other tools or state, but generally complete for a simple toggle tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It extensively explains the password parameter: must match configured password, compared tolerantly, reason for tolerance (voice transcription), and ethical warnings. This adds immense value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Turn OFF exhibition mode, restoring full normal control.' It clearly identifies the verb (exit) and resource (exhibition mode), and distinguishes itself from siblings like enter_exhibition_mode and get_exhibition_mode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-call: only when user explicitly asks and provides password. Gives clear warnings: never guess or supply password yourself, never reveal password. Also instructs to ask user to retry on wrong password. This is exemplary usage 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 provided, the description fully explains the tool's behavior: it is a read-only operation with no side effects. It also details the nuance of the INCONSISTENT state when has_feedback_sensor is false, preventing misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core purpose, then detailing the argument, side effects, and edge-case behavior. Each sentence serves a clear purpose without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description explains the return fields (has_feedback_sensor) and how to interpret the state. It addresses common confusion about the INCONSISTENT state, making the tool's behavior fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'name' is thoroughly described with examples (JMRI system name and user-friendly label), clarifications on case-insensitivity, and allowance for unambiguous fragments. This adds significant value beyond the schema's minimal definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the current state of one turnout, using specific verbs ('Get') and resource ('turnout'). It distinguishes from siblings like 'set_turnout' and 'list_turnouts' by focusing on a single read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'No side effects — this only reads state, it never changes the turnout', providing clear context for safe read-only usage. However, it does not explicitly contrast with alternatives like 'set_turnout' for mutations or 'list_turnouts' for listing all turnouts.
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: that any field can be empty (normal), explains details for groups, dcc_system, dcc_system_name, max_speed_percent scaling, and explicitly states 'No side effects.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is somewhat lengthy but well-organized: begins with purpose and field list, then usage guidance, then detailed field explanations. Every sentence adds value, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description thoroughly explains all return fields and edge cases (empty fields, null values). Covers usage context, side effects, and practical tips. Complete for a list-all tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. Baseline is 4, and the description does not need to add parameter info because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists every locomotive in JMRI's roster with specific fields enumerated. It explicitly distinguishes itself from the sibling tool find_locomotive, which resolves names to addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (before acquire_throttle/set_speed) and when not to (for name-to-address resolution, use find_locomotive). Also explains it's the only way to map loco names to DCC addresses.
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?
Discloses important behavioral detail about the 'has_feedback_sensor' field and how to interpret INCONSISTENT state, which is critical for correct agent reasoning, especially with no annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence is informative and essential, front-loaded with main purpose, followed by usage guidance and a nuanced behavioral note. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main output fields and their interpretation, though could explicitly list all return fields. Given no output schema, it does well to contextualize the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds value by explaining output semantics, compensating for lack of output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all turnouts with their state, using specific verbs ('list', 'discover') and distinguishes from siblings like get_turnout and set_turnout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (before get_turnout/set_turnout, to answer specific queries) and declares no side effects, guiding appropriate invocation.
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 turns on lights via two sub-commands, does not affect speed/direction/power/clock, and is visual-only. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: main action, usage hints, exclusions, inverse, return value. Slightly verbose but every sentence adds value; could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully explains the composite action, what it changes and doesn't change, and describes the return shape despite no output schema. Adequate for a zero-parameter tool with clear behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%, meeting baseline. The description adds context by explaining the tool as a composite of set_layout_lights and set_all_locos_lights, giving semantic meaning to the lack of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it sets layout to night mode by turning on all layout lights and locomotive lights, distinguishes from power/status commands, and names inverse (day_mode). Explicitly specifies it does not affect speed, direction, power, or signals, differentiating it from sibling tools like set_power, set_speed, and set_signal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides natural language examples ('put the layout in night mode'), states it's for demonstration-style lighting scenes, and explicitly lists what it does NOT do (track power, signals, etc.), guiding the agent on when to use and when to avoid.
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 provided, but description fully discloses that this is a drastic action that cuts power to all systems, requires explicit re-powering, and re-reads and confirms results per system. References set_power's docstring for an upgrade note, showing awareness of version-specific behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Somewhat verbose with alternative phrasings and comparisons, but each sentence adds value. Could be slightly more concise, but the information is well-organized and front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return behavior (confirmation per system), side effects (power loss and need for re-powering), and contextualizes relative to siblings. It fully explains the tool's behavior and impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so no parameter description needed. The description does not discuss any input schema details, but that is appropriate given zero parameters. Baseline 4 for no-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Cut power to EVERY DCC system at once' with explicit verb 'cut power' and resource 'all DCC systems'. Clearly distinguishes from sibling emergency_stop_all by explaining the scope (all locos regardless of session) and the fact it cuts power, not just e-stops. Also provides alternative phrasings like 'coupe le courant' to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call for generic power-cut request with no specific system named' and contrasts with emergency_stop_all when user mentions 'power' vs 'stop'. Warns not to use for routine stop and explains re-powering requirement. Provides clear when-to-use and 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?
No annotations are provided, so the description carries the full burden. It discloses internal steps (power_on_all, prepare locomotives), edge cases (exhibition mode refusal, power-on failure skipping step 2), and return structure. This is comprehensive 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary first, followed by usage call, steps, limitations, and return format. It is slightly wordy but every sentence adds value. Could be tightened slightly, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description includes the return format. It covers inputs, behavior, edge cases (exhibition mode, failure), and follow-up actions. It is complete for a session start tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema covers everything. The description adds no parameter-specific detail, but since there are zero parameters, a baseline of 4 is appropriate per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Begin a driving session: power on every DCC system, then prepare every already-acquired locomotive.' It uses a specific verb and resource, and the steps differentiate it from siblings like power_on_all or prepare_locomotive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it is the 'one-call opener' with example phrases. It states when not to use it (does not acquire new locomotives) and suggests alternatives ('follow up with prepare_locomotive/acquire_throttle'). It also notes refusal in exhibition mode and failure behavior.
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 provided, so description carries full burden. It discloses that this is JMRI's actual decoder e-stop (speed -1.0), cuts power abruptly, is rougher on mechanism, and is safe to call repeatedly with a silent no-op for redundancy. Also mentions auto-acquires throttle and returns confirmed status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a lead sentence, argument section, and detailed usage notes. While it is longer than necessary, every sentence adds value and the structure aids readability. Minor redundancy ('Auto-acquires the throttle if needed' could be integrated into the argument description).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is fully complete. It covers purpose, parameter meaning, behavioral details, usage guidelines, and return value. No gaps remain for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (address) with 0% schema coverage, so description compensates fully. It explains 'DCC address' and that it auto-acquires the throttle if needed, adding useful meaning beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool performs an immediate emergency stop using JMRI's decoder e-stop command. Specifies the action (emergency-stop), resource (locomotive), and method (decoder e-stop). Distinguishes from routine stop by emphasizing it's for safety-critical situations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use ONLY for safety-critical stops: derailment risk, imminent collision, or any situation needing an immediate halt.' Also explicitly warns not to use as a synonym for routine 'stop', providing clear exclusion guidance. No mention of sibling tools, but the guidance is sufficient.
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 details the ordered process (ramp stop, release, power off), mentions that layout lights are untouched, that one failure doesn't block the rest, and specifies the return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main action, then details the ordered steps and contrasts with siblings. Every sentence adds value; it is appropriately detailed for a multi-step tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description provides the return value structure, explains the entire process, and clarifies what is not affected. It is complete for an end-session tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, so baseline is 4. The description does not add parameter info because none exist, which is appropriate. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ends a driving session, stops/park locomotives, and cuts power. It distinguishes itself from siblings like secure_layout and power_off_all. The verb 'end' and resource 'session' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Call for "let's stop"/"termine la session"/"on arrête"' and explicitly contrasts with secure_layout and power_off_all alone, saying 'NOT secure_layout... NOT power_off_all alone'.
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 behavioral traits: it explains that power_on_all and set_power(turn_on=True) are refused, locomotives move forward only at fixed speed, address allowlist restrictions, and that lights and functions remain unrestricted. Also documents the deliberate asymmetry in requiring a password to exit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While lengthy, every sentence adds value. The description is well-structured with a clear opening, bullet points for restrictions, and logical flow. It is front-loaded with the core purpose and efficiently conveys complex behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 0 parameters, no output schema, and no annotations, the description is fully self-contained. It covers activation, exact behavioral changes, what remains unaffected (lights), and exit strategy, leaving no gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline score of 4 applies. The description does not need to add meaning to parameters since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Turn ON exhibition mode: a restricted-safety mode for public demos'. It specifies the verb (turn on) and resource (exhibition mode), and effectively distinguishes it from its sibling exit_exhibition_mode by explaining the asymmetry in password requirements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'for public demos (exhibitions, kids trying voice control)', 'whenever the layout is about to be unsupervised or handed to the general public'. Also mentions that no password is needed and that it can be freely called, and directs to exit_exhibition_mode for deactivation.
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 provided, so description carries full burden. It discloses no side effects, independent fetching per section, and error key handling on failure. Full 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and concise; each sentence provides essential information without redundancy. Front-loaded with purpose, then usage, then behavior, then output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description sufficiently explains return structure and error handling. Covers all relevant aspects for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 applies. Description adds no parameter info but none is needed; schema coverage is 100% (trivially).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides a 'one-call overview of the whole layout' listing specific components (connectivity, power, locomotives, blocks, sensors). Distinguishes from sibling system_status by scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to call ('what's happening on the layout?') and when not to call (use system_status for reachability/power only). Advises against chaining multiple calls.
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 provided, but description fully covers behavior: read-only, no side effects, returns state, describes what sensors represent (block occupancy, etc.). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with core purpose, followed by useful context and usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a zero-parameter list tool: explains what it lists, the state returned, the meaning of sensors, and usage scenarios. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100% with empty properties. Baseline 4 for zero parameters applies. No additional parameter info needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'every sensor known to JMRI', specifying the output includes current state. This distinguishes it from sibling tools like get_sensor (single sensor) and other list tools (list_turnouts, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'before calling get_sensor' and for answering specific questions. Also notes read-only nature, helping agent decide between this and mutation tools.
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 transparency burden. It explicitly states 'No side effects' (read-only behavior), discloses output details (current aspect and 'lit' status), and gives a usage warning about validating aspects before set_signal. This is strong 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core purpose. Every sentence adds value: first defines the function, second gives usage guidance, third provides cross-tool context. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-param list tool, the description is complete. It covers what the tool does, when to use it, that it has no side effects, what output fields to expect (aspect, lit), and how to follow up with related tools. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The description adds no parameter details (none needed) but does illuminate output semantics, which is helpful. No deductions necessary; it fully meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List every signal mast known to JMRI, with its current aspect.' It clearly distinguishes its scope (all masts, with aspects) from related sibling tools like get_signal, set_signal, and list_signal_aspects by explicitly pointing to those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Use to discover what signal masts exist, or answer "what signals are there?"...' and even directs to alternative tools for related tasks (signal_off for darkening, list_signal_aspects before set_signal). This fully addresses usage context and alternative 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?
No annotations exist, so description fully covers behavior: four-step sequence, server-side looping, independence per locomotive, scope limited to session's throttles, empty response for no acquisitions, non-blocking failures. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured, front-loaded with main action, followed by contrasts and details. Every sentence serves a purpose (clarifying scope, alternatives, behavior). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return format and error handling. Covers all relevant aspects: scope, sequence, comparisons, edge cases. Highly complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description adds context about the tool's action and behavior beyond the schema, earning a baseline 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool puts every currently-acquired locomotive to rest with a specific sequence. It distinguishes itself from park_locomotive (single loco) and emergency_stop_all (motion-only), 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: use park_locomotive for one named loco, emergency_stop_all for motion-only. Warns against looping park_locomotive, stating this tool loops server-side. Clear when to use and not use.
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 details the four steps, edge cases (never acquired, reverse direction, auto-acquire for lights), and what the tool does NOT affect (system power, other locomotives). No annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but every sentence adds valuable detail. It is front-loaded with a summary. Could be slightly trimmed, but overall efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-step, edge cases) and lack of output schema, the description covers everything needed: steps, edge cases, return value structure, and contrasts with alternatives. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'address' has no description in the input schema (0% coverage). The description adds full meaning: 'The locomotive's DCC address', which is clear and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool puts one locomotive to rest for the session, with specific actions (smooth stop, forward, lights off, throttle released). It distinguishes from siblings like 'stop', 'emergency_stop', and 'set_power' by explaining what those tools do differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use (end-of-session shutdown for one locomotive) and when not to use (mid-run pause, use 'stop'). Provides alternative natural language commands and contrasts with 'stop', 'emergency_stop', and 'set_power'.
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, so description fully handles transparency. Discloses that power restoration does not resume locomotive speeds, that each system result is confirmed, and that exhibition mode refuses the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and informative, but slightly verbose with tangential notes (e.g., outdated_jmri_version). Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, description covers all relevant aspects: behavior, side effects, edge cases, and interactions with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, and description explicitly notes 'No arguments.' Schema coverage is 100%, so nothing more needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it restores power to all DCC systems at once. Differentiates from sibling tools like set_power and power_off_all by specifying it is a global operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (e.g., after a layout-wide power cut) and when not to (exhibition mode). Contrasts with alternatives like set_power for individual systems.
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 that it only touches the locomotive's session state (throttle + lights), does not set speed, and is safe even if throttle already held. It details the three steps and the outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points for arguments, clear separation of sections, and no wasted sentences. Slightly longer than necessary but still efficient; a minor trim could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, parameters, usage steps, what it does not do, and explicit return format. Given no output schema, the return description is complete and helpful for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains 'address' as DCC address and 'prefix' as optional command station prefix with examples, including its auto-detection behavior when omitted. This adds essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool prepares one locomotive for a session with three steps: acquire, face forward, lights on. It contrasts with siblings like park_locomotive, stop, emergency_stop, and set_power, making its unique purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides example usage phrases ('prépare la loco', 'prepare the 3'), warns against using stop/emergency_stop/set_power for this purpose, and advises against calling individual tools in sequence for a prepare request.
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: speed/direction untouched, functions turned off if active, only reaches this session's acquired locos, independent attempts per loco, returns empty array for nothing acquired. All important traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: lead sentence, purpose, behavior details, comparisons, edge case, return format. Every sentence adds value without redundancy. Compact yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains the return structure and error handling ('not an error'). It covers all necessary context for a zero-parameter tool, including edge cases and independent execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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-level detail (none needed) but explains the tool's effect clearly, which is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Release this session's throttle on EVERY currently-acquired locomotive, without changing their state.' It clearly distinguishes from siblings like park_all_locomotives and emergency_stop_all by naming them and contrasting behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'ending a session or handing off without stopping anything.' It also gives exceptions (functions turned off) and contrasts with similar tools, providing clear guidance on 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?
Discloses it turns off active functions automatically and warns about unpredictable decoder state if released with functions on. No annotations present, so description carries full weight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main intent, args section, and usage notes. Slightly verbose but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema and no output schema, the description covers purpose, usage, parameter meaning, side effects, and safety warnings completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description explains the 'address' parameter as 'The locomotive's DCC address', adding essential meaning not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states this releases control of a locomotive acquired with acquire_throttle, distinct from sibling tools like acquire_throttle or set_speed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it's good practice when done controlling a loco, but not required for correctness as JMRI auto-releases on connection close.
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: the sequence of steps (ramped stop, lights off, throttle release), parameter effect, return format, and what it does NOT do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (Args, sequence), but slightly lengthy. Every sentence adds value, but could be tightened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (multi-step, parameter, sibling comparisons) and no output schema, the description is complete: covers purpose, usage, behavior, parameter, and return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains the release_throttles parameter in detail, including default and effect, fully compensating for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Put the whole layout into a known safe resting state — the end-of-session command.' It uses specific verbs and resources and explicitly distinguishes from siblings like power_off_all and emergency_stop_all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('Call for I'm done for today, secure the layout') and when-not-to ('Never chain stop/set_loco_lights/set_layout_lights/release_throttle yourself'), and contrasts with 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?
Despite no annotations, the description fully discloses behavior: loops server-side, independent attempts per locomotive, one failure doesn't block others, returns list of results. Also explains scope: only affects locomotives acquired this session and that nothing acquired returns an empty array, not an error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a clear main sentence followed by Args, usage notes, and return info. Slightly redundant mentioning the looping behavior twice, but overall efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single boolean parameter and no output schema, the description covers all needed context: input meaning, behavioral scope, return format, error handling, and alternatives. It is fully self-contained and leaves no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'state' is fully explained in the Args section: 'True to turn every light-related function on for every locomotive, False to turn them all off.' Although context signals indicate 0% schema description coverage, the actual description provides complete semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb and resource: 'Turn ON/OFF EVERY light-related function of EVERY currently-acquired locomotive at once.' It clearly distinguishes itself from siblings by naming alternatives: set_loco_lights for one locomotive and set_layout_lights for layout/scenery lighting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use criteria: 'Call for "turn on/off all the lights of all the locos"... Never loop set_loco_lights/set_function yourself.' It also states when not to use: 'For ONE named locomotive use set_loco_lights' and 'For layout/scenery lighting... use set_layout_lights.' Includes scope limitation referencing emergency_stop_all.
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 behaviors: auto-acquires throttle, does not enforce stopping, returns direction as string independent of speed, is safe to call repeatedly (no-op), and handles exhibition mode explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, clear sections for args, best practices, return value, and edge cases. Slightly verbose but every sentence adds value; could be trimmed slightly for extreme conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no output schema, and no annotations, the description is exceptionally complete: covers all behavioral aspects, edge cases (exhibition mode, redundant calls), return format, and ties to related tool (enter_exhibition_mode).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains both parameters thoroughly: address (DCC, auto-acquire) and direction ('forward'/'reverse', case-insensitive, meaning relative to decoder). Adds crucial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a locomotive's direction to 'forward' or 'reverse' using a DCC address. It distinguishes from sibling tools like set_speed and stop by specifying the exact action and parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use: best practice to stop a moving loco first, warns of jolt/ignored command, explains behavior in exhibition mode (reverse refused), and suggests flipping current direction for 'turn around'.
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, description discloses full behavioral impact: toggles narration, and crucially states it does not silence errors or safety confirmations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with key purpose, well-organized with paragraphs for different aspects, but somewhat verbose with repetitions; still very effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple boolean toggle, description covers default behavior, when to invoke, edge cases, and exceptions (errors/safety), leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully explains the single boolean parameter: True/False meanings and usage scenarios, going beyond just typing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Turn executor mode (concise, no-narration responses) on or off.' Identifies the specific verb and resource, and distinguishes from sibling get_executor_mode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says call only when user asks to change response style, provides concrete examples for True/False, and notes it's unnecessary at conversation start.
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?
Details auto-acquire throttle, label matching (English/French, case/accent-insensitive), catch-and-continue per function, and that no light-labeled functions returns a note. No annotations, so description carries full burden and meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with args, behavior, examples, sibling distinctions, and return format. Slightly long but every part adds value. Could be trimmed slightly without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format (address, applied list, failed list), edge cases (no light-labeled functions), and complex behavior (label matching, language detection) without needing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully explains address (DCC address, auto-acquires throttle) and state (boolean for on/off) and how they are used in the logic. Adds significant meaning beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it turns ON/OFF every light-related function of ONE locomotive. Distinguishes from sibling tools like lights_on/lights_off (F0 only) and set_function (requires looping).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: for 'all'/'every' lights with a named locomotive. Provides alternative tools for 'all locos' (set_all_locos_lights) and layout lighting (set_layout_lights). Advises against looping set_function.
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: auto-acquires throttle, clamps speed, no-op on redundant commands, exhibition override, and return value details (actual speed as % of loco's max, includes direction/system conditionally).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear Args/Returns sections, but slightly lengthy. However, every sentence provides necessary detail without redundancy. Minor opportunity to tighten.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and no annotations, the description covers all behavioral aspects, edge cases (clamping, no-op, exhibition mode), and return value structure. Fully compensates for missing structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description adds extensive meaning: address (auto-acquires), speed_percent (0-100, clamped), direction (optional, case-insensitive, atomic set, leaves untouched if omitted, flips instantly). Also explains return value details for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets a locomotive's speed as a percentage, distinguishing it from siblings like set_speed_ramped, emergency_stop, stop, and set_direction. It covers automatic throttle acquisition and atomic direction setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using stop or emergency_stop instead of speed_percent=0, recommends set_speed_ramped for duration or ramped direction changes, and notes exhibition mode override. Provides clear when-to-use and 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, the description fully discloses idempotency, release on disconnect, exhibition mode rejection, and the return field 'system' — covering all important behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then args, usage, safety, and return note. Every sentence adds unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and only two parameters, the description covers acquisition purpose, return content, error conditions (exhibition mode), and integration with other tools—fully adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, but the description explains both parameters in detail: address is required, prefix is optional with clear guidance on auto-detection vs explicit override.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb-object pair ('Acquire control of a locomotive by its DCC address') and clearly distinguishes from sibling tools like set_speed and stop by noting auto-acquire behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call directly (to get current state or override prefix) versus letting auto-acquire handle it, and mentions release and exhibition mode restrictions.
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?
Discloses that the tool is read-only, has no side effects, and that the state comes from hardware detection via a linked sensor, not from a user command. This is especially important with no annotations, as it fully informs the agent about safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: a one-sentence synopsis followed by an Args section. Every sentence adds value, no redundancy. The formatting is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, the description covers purpose, exact parameter semantics, usage guidance, differentiation from siblings, and behavioral traits. No output schema is needed because the return value (occupied/unoccupied) is implied. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description thoroughly explains the 'name' parameter: it can be a JMRI system name, user-friendly label, or unambiguous fragment, and is case-insensitive. This adds critical meaning beyond the schema's minimal 'Name' field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets the OCCUPIED/UNOCCUPIED state of a layout block, with specific verb and resource. It also distinguishes from get_sensor by specifying when to use each tool. Sibling tools like get_sensor and list_blocks further differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use this tool (to answer 'is block X occupied?' when user names a layout block/section specifically) and when not (if they name a sensor directly, use get_sensor). Also states read-only and that no set_block tool exists, preventing misuse.
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 discloses important traits: 'No side effects' (read-only), return format 'Returns {"aspects": [...]}', the real subset of the mast, case-sensitivity of aspects, and error behavior for non-standard names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main action. It includes parameter details and key behavioral notes in a structured format (Args, notes) without fluff. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is complete: it covers the input semantics, return format, case-sensitivity, exclusions, and side-effect safety. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates: it explains that 'name' is a 'Mast name (system name or userName) or unambiguous fragment' and is 'Case-insensitive'. This adds meaning well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List valid aspect names for one mast' with a specific verb and resource. It distinguishes itself from siblings by noting its purpose 'to pick an exact spelling before set_signal' and excluding 'unlit'/'off' (use signal_off).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'to pick an exact spelling before set_signal'. Also provides an alternative: 'Excludes "unlit"/"off" (use signal_off)'. This gives clear usage context and contrasts with sibling tools.
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?
Discloses that it applies one state to all turnouts with no per-turnout memory, warns of motor movement on real layout, and explains catch-and-continue error handling. No annotations were provided, so description carries full burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for Args, Call for, Blast radius, Returns. Every sentence adds value; no fluff. Efficiently conveys complex information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive: covers purpose, usage, parameter, return format (succeeded/failed lists), error handling (catch-and-continue), and safety warnings. No output schema needed given the clear return description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameter description (0% coverage), but description fully explains the boolean 'thrown' parameter: true means THROW, false means CLOSE. Adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it sets every turnout to the same state (all closed or all thrown) in one call, with specific verb and resource. Distinguishes from sibling set_turnout by saying 'Never loop set_turnout yourself'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (for layout-wide requests) and when not to (not as a shortcut for one turnout). Provides alternatives (use set_turnout for single turnout) and warns about blast radius.
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 side effects: 'Writes to JMRI,' case-sensitivity, and lack of local validation. It also explains the meaning of 'confirmed' false, providing transparent feedback behavior beyond the raw action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence serves a purpose: purpose, parameter details, usage guidance, side-effect disclosure, and return interpretation. The structure with 'Args:' and a note is clean and front-loaded, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains what is reported (observed aspect) and the meaning of the confirmed flag. It also covers prerequisites, alternatives, and edge cases (unlit/off), making the tool sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions, but the description richly annotates both parameters: name (system/user/fragment, case-insensitive) and aspect (examples, case-sensitivity, no validation, special darkening values, and referral to list_signal_aspects). This fully compensates for the schema's bareness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Set a signal mast's aspect, and report the aspect actually observed,' which uses a specific verb and resource. It clearly distinguishes from siblings like signal_off (darkening) and list_signal_aspects (reading aspects) by mentioning them as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: call list_signal_aspects first if unsure of spelling/case, and prefer signal_off for darkening. This directly tells the agent when to use this tool versus alternatives, avoiding guesswork.
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:

[![MrJ-JMRI-MCP MCP server](https://glama.ai/mcp/servers/HO44-PROJECT/MrJ-JMRI-MCP/badges/card.svg)](https://glama.ai/mcp/servers/HO44-PROJECT/MrJ-JMRI-MCP)

Score Badge

Copy to your README.md:

[![MrJ-JMRI-MCP MCP server](https://glama.ai/mcp/servers/HO44-PROJECT/MrJ-JMRI-MCP/badges/score.svg)](https://glama.ai/mcp/servers/HO44-PROJECT/MrJ-JMRI-MCP)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/HO44-PROJECT/MrJ-JMRI-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server