labgrid-mcp

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation4/5
Most tools have distinct purposes (e.g., get_power_state vs set_power, console_open vs console_read). A few pairs like release_place/release_from and who/list_places could be confused, but their descriptions clearly differentiate them. Overall boundaries are clear.
Naming Consistency4/5
The vast majority of tool names follow a verb_noun pattern (list_places, reserve, acquire_place, set_power). Exceptions like coordinator_info and who break the pattern, but they are minor and the naming is otherwise predictable.
Tool Count2/5
38 tools is well above the 25-tool threshold, making the surface feel heavy. While the domain is broad, the high count may overwhelm agents, and some tools could be consolidated (e.g., a single console tool with subcommands). The scope justifies some breadth, but this exceeds reasonable limits.
Completeness4/5
The tool set covers core lifecycle operations: place inspection, reservation management, acquisition/release, hardware control (power/IO/SD/USB), console, SSH, file transfer, and port forwarding. Minor gaps include no delete_place, no get_reservation by token, and no explicit listing of console sessions, but these are workable shortcomings.
Average 4.2/5 across 38 of 38 tools scored. Lowest: 2.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 16 commits in the last 12 weeks
- Last stable release on August 6, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.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.
This repository includes a glama.json configuration file.
This server has been verified by its author.
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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the context 'live unary RPC to the coordinator', implying a direct, real-time query rather than a cached view. However, it doesn't elaborate on return behavior, pagination, or any other behavioral nuances. This is a minor addition beyond the annotations, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but it is under-specified rather than concisely informative. It omits a clear action verb and leaves the reader to infer that the tool lists reservations. Effective conciseness requires clarity; this lacks both.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with zero parameters and an output schema exists, the description is too vague. It doesn't explicitly say it returns a list of reservations, what constitutes 'current', or how this relates to the coordinator. The description leaves too much ambiguity for a tool that should be straightforward to describe.
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 zero parameters and the schema is fully covered, so the description doesn't need to explain parameters. The baseline for 0 params is 4, and the description doesn't introduce any parameter-related ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Current reservations (live unary RPC to the coordinator)' is a noun phrase that restates the tool name without a clear verb like 'list' or 'gets'. It doesn't distinguish this tool from sibling list tools such as list_places or list_resources, and the technical detail about the RPC adds confusion rather than clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention any exclusions, prerequisites, or scenarios where another sibling tool would be more appropriate, leaving the agent without direction for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only restates the mutating nature of the operation ('Set') and references a driver method, adding no behavioral context beyond the destructiveHint annotation. It does not disclose side effects on active USB connections, reversibility, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence, front-loading the core action. It is appropriately sized for a simple tool but relies heavily on the driver name, which may be cryptic. It is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive, non-idempotent operation with parameters that have no schema descriptions, the description is not complete enough. It lacks critical information about link values, ordering, persistence, and what 'links' mean. The presence of an output schema does not compensate for the missing parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameters. It clarifies that 'place' should be an acquired place, but 'links' is only described as 'USB mux links' without any detail about valid formats, link names, or how to specify multiple links. This is insufficient.
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 a specific verb 'Set' and identifies the resource as 'USB mux links' on an 'acquired place', and references the driver method for precision. It distinguishes this from sibling tools like set_sd_mux or set_io by specifying USB mux and the acquired place requirement.
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 phrase 'on an acquired place' implies the tool should only be used after acquiring a place, but there is no explicit guidance about when to choose this tool over alternatives like set_sd_mux, nor any exclusions or prerequisites beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that returns are 'labgrid place dicts', which gives some behavioral context about output format, but does not disclose details like ordering or pagination. This is acceptable given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. Every phrase adds context (scope, return type), making it appropriately concise without being under-specified.
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 (0 params, rich annotations, and an output schema), the description adequately states the scope and return format. It could explicitly say 'returns a list' but the plural 'All places' implies it, and the output schema likely covers structure.
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, and the schema is empty with 100% coverage by default. The description need not explain any parameters, and the baseline of 4 applies for no-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'All places known to the coordinator, as labgrid place dicts' clearly identifies the resource (places) and scope (known to the coordinator), but lacks an explicit verb—relying on the tool name for the action. It distinguishes from sibling show_place by implying a plural listing, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings like show_place, list_resources, or coordinator_info. It does not state any usage context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (read-only, idempotent, non-destructive), so the description doesn't need to repeat that. It adds useful context about 'exporter resources' and the coordinator as the source, but doesn't disclose behavior like ordering, pagination, or live-state semantics. This is acceptable given the annotations, but not richly 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?
The description is a single, concise sentence that contains only meaningful information. There is no redundancy or filler, making it easy to parse quickly.
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 parameterless list operation with a well-defined output schema and thorough annotations, this description is mostly complete. It would benefit from an explicit statement that it returns a list and how it relates to list_places, but the overall context is adequate for an agent to invoke it in simple scenarios.
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 and the schema is an empty object with 100% coverage. No parameter explanations are needed, and the baseline of 4 applies for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns all exporter resources known to the coordinator, which is clear and specific about the resource type and scope. It distinguishes from sibling tools like list_places by specifying 'exporter resources', though it lacks an explicit verb like 'lists'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as list_places or coordinator_info. The context is implied by the name, but explicit usage instructions and exclusions are absent.
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?
Annotations declare destructiveHint=true, and the description adds a non-obvious guarantee that no ownership check occurs and a brand-new name won't collide with existing acquisitions. This is valuable context beyond the annotations, though the term 'acquisition' is ambiguous.
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 at two short sentences and front-loads the primary action. The second sentence is cryptic, but overall it is efficient and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, so the description doesn't need to explain return values. It covers the core operation and a behavioral note, but lacks context about what a 'place' is, any prerequisites, or consequences of duplicate names. Given the simplicity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required `name` field with 0% description coverage. The description's 'by name' merely restates the parameter, and the collision note provides a weak guarantee about name behavior but no concrete constraints, format, or uniqueness rules. It does not sufficiently compensate for the missing 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?
The description clearly states 'Create a new place by name,' giving a specific verb and resource. This unambiguously differentiates add_place from sibling tools like acquire_place or add_place_alias, even though alternatives are not explicitly named.
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 usage: it creates a new place, contrasting with acquire_place which likely targets existing places. However, there is no explicit 'when to use' or exclusion of alternatives, and the ownership-check note is a behavioral caveat rather than a usage recommendation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the destructive nature, so the description doesn't need to repeat that. It adds the constraint that the place must be 'acquired', which is useful behavioral context beyond the annotations. However, it doesn't elaborate on potential side effects or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. No filler words; every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and annotations covering safety, the description is adequate for a simple tool. It mentions the key precondition ('acquired place') but leaves out parameter details and alternative tool guidance, making it incomplete for a fully unassisted agent.
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?
With 0% schema description coverage, the description provides some meaning: 'mode' is the SD mux mode and 'place' is the acquired target. It does not enumerate valid mode values or clarify the place format, but it does offer basic semantics for both 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 the tool's function: setting the SD mux mode on a place. It uses a specific verb+resource construction and the mention of the driver call (USBSDMuxDriver.set_mode()) further disambiguates it from related tools like set_usb_mux.
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 usage on an 'acquired place', which is a prerequisite, but does not explicitly state when to use this tool over siblings or provide exclusions. The context is clear but alternatives are not discussed.
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?
Annotations already cover read-only and idempotent behavior. The description adds useful context that the data is 'derived from the snapshot', indicating freshness and source, which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose without any filler. Every word contributes to understanding the tool's function, making it highly 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?
For a zero-parameter, read-only query with an output schema, the description provides sufficient context about what is returned (acquired places) and the data source (snapshot). The slight ambiguity about the output structure is acceptable given the output schema exists.
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 takes zero parameters, so there are no parameter semantics to clarify. The input schema is an empty object, leaving no gaps for the description to fill.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool reports currently acquired places by host/user, which is a specific resource and scope. However, it lacks an explicit verb like 'list' or 'show', so the action is implied rather than stated. It distinguishes from siblings by focusing on acquired places rather than all places.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like list_places or show_place. The description does not mention exclusions or provide context for selecting 'who' over other read-only query tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, non-readonly), the description adds crucial behavior: empty-string values delete keys, and it explains the labgrid semantics and force override. This is valuable context not derivable from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, then explains the non-obvious deletion semantics in a structured aside. The labgrid design reference adds mild verbosity but doesn't obscure the message.
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 annotations (destructive, non-idempotent) and the presence of an output schema, the description covers the key edge cases (empty-string deletion, force override) and acquisition constraint. It is sufficient for an agent to use the tool correctly without further investigation.
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?
With 0% schema description coverage, the description compensates by explaining tags deletion semantics and the force parameter's role. 'place' is self-evident, so it doesn't need extra detail. The description adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Set tags on an existing place'), clearly distinguishing it from sibling tools like set_place_comment. However, it does not explicitly name alternatives for differentiation, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via the verb+resource but provides no explicit alternatives or exclusions. It does note a refusal condition ('Refuses if the place is acquired by a DIFFERENT identity unless force=True'), which gives some contextual guidance, but that's more behavioral than usage-vs-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?
The description goes beyond the annotations by disclosing the two-step behavior (HttpDigitalOutputDriver.set() then .get()), the fact that the same resource_name applies to both set and re-read, and the fallback behavior when resource_name is omitted. This adds valuable context about side effects and result handling. The annotations already indicate mutability/destructiveness, so the description complements rather than repeats them.
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 succinct and front-loaded, starting with the core operation in the first sentence. The second sentence about resource_name is focused and provides necessary parameter context. No extraneous content is present, though the reference to "§11.14" is cryptic without further context. Overall, 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 output schema and annotations, the description covers the main operational context: the set-then-get behavior, the need for an acquired place, and the key resource_name parameter. It is missing the precise meaning of the value parameter (e.g., true = high/on), which is critical for correct invocation. However, the output schema likely handles return values, and the annotations cover safety. The description is nearly complete with one notable gap.
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?
With 0% schema coverage, the description carries a heavy burden for parameter explanation. It thoroughly explains resource_name (picking one of several same-class IO resources, same for set and re-read, omission preserves single-resource behavior). However, it does not explain value's boolean semantics (what true/false does to the IO) or elaborate on place beyond 'an acquired place.' The description partially compensates for the schema's lack of descriptions but leaves two of three parameters underspecified.
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: "Set digital IO on an acquired place, then re-read and return the resulting state." It identifies the specific resource (digital IO on an acquired place) and distinguishes itself from siblings like get_io (which presumably only reads) by explicitly mentioning the set-then-get sequence and the reuse of the same resource_name for both operations.
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 usage context: it is for setting digital IO and immediately verifying the result. It explains the resource_name parameter's role (picking among same-class IO resources) and that omitting it preserves single-resource behavior, but it does not explicitly compare to alternatives like get_io or state when not to use this tool. The guidance is present but not fully explicit about when vs. 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?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds a meaningful behavioral detail: raising a tool error if the place is unknown. 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?
Two extremely short sentences, each earning its place. Front-loaded with the core purpose and then the error condition. No 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?
For a single-parameter lookup tool with an output schema and read-only annotations, the description is complete. It covers the required behavior (exact match, error on unknown) without unnecessary elaboration.
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?
Schema has one parameter 'name' with no description. The phrase 'exact name' adds important matching semantics beyond the schema, but leaves other aspects like case sensitivity or format unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"One place by exact name" clearly indicates the tool retrieves a single place by exact name, and the error-on-unknown behavior adds specificity. It is distinguishable from sibling list_places, though it lacks an explicit verb like 'shows' or 'gets'.
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 use when an exact place name is known, and the error behavior warns against using it with potentially incorrect names. However, no explicit alternatives or when-not-to-use guidance is provided relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint and readOnlyHint annotations, the description reveals the idempotency nuance, the force condition, and the return value behavior (refreshed place dict with bounded snapshot catch-up). This adds meaningful operational context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary action, followed by concise but technically rich notes. It's longer than a single sentence but each sentence adds value for a mutating coordination tool.
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 place alias mutation with 3 params and an output schema, the description covers behavior, return, and a key race condition. It omits auth/error details but is sufficient given the schema and output schema.
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?
Schema has zero descriptions, so the description carries the burden. It explains the force parameter and implies place, but doesn't clarify alias format or place identifier semantics. It partially compensates but leaves some param details unspecified.
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 opens with a specific verb and resource ('Add an alias to an existing place'), clearly distinguishing it from sibling tools like add_place, delete_place_alias, and set_place_tags. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when the tool applies, such as the idempotency of duplicate alias insertion and the refusal on place acquisition by another identity unless force=True. It does not explicitly name alternative tools or exclusion criteria, but the conditions are concrete enough for an agent to decide.
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?
The description adds value beyond annotations by explaining the internal sequence (stop and join reader, deactivate driver) and disclosing the error condition for unknown sessions. This complements the idempotentHint annotation without contradiction.
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, consisting of two sentences that front-load the primary action and include essential behavioral details. There is no redundant or filler content.
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, output schema present), the description covers the core behavior, idempotency, and error handling. It is complete for a close operation, though it could be slightly more explicit about the session parameter's provenance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one 'session' parameter with no description, and the tool description only references it indirectly through 'unknown session'. It does not explain the format, how to obtain the session ID, or any expectations, which is insufficient given 0% schema description coverage.
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 with a specific verb and resource: 'Close a console session', and provides implementation details ('stop and join its reader, then deactivate the driver'). This distinguishes it from sibling tools like console_open, console_read, and console_send.
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 implies when to use the tool by defining it as closing a session, and the 'Idempotent' and 'unknown session is a tool error' notes give guidance on expected behavior. It does not explicitly name alternatives, but the context provided by sibling tool names is sufficient for a clear use case.
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?
Annotations already declare idempotent and non-read-only behavior. The description adds valuable context beyond those: best-effort execution and the specific error condition for unknown tunnel ids.
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 concise sentences, front-loaded with the main action, and no unnecessary wording. The structure is clean and efficient.
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 idempotent close operation with an output schema, the description covers the essential behavior and error semantics. It does not mention how to obtain valid tunnel ids, but sibling forward_list implies that source.
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?
With 0% schema description coverage, the description compensates by tying the 'forward' parameter to the tunnel id ('by id'). It does not detail the id format, but the single parameter's purpose is clear from the 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?
Clearly states the action 'Close a forward tunnel by id' with the specific ssh -O cancel reference. The verb and resource are precise, and it is readily distinguished from siblings like forward_open and forward_list.
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?
Provides useful context: closiing is by id, best-effort, and unknown tunnel ids cause errors. However, it does not explicitly mention when to use this tool versus alternatives, leaving that to be inferred from sibling tool names.
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 annotations indicating this is not read-only or destructive, the description adds context by explaining the local_port=0 auto-assignment, return keys, allowance of multiple tunnels, and the ordering of ownership check before registry calls. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences that front-load the purpose and then add relevant behavioral and parameter details without fluff.
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?
The description covers the operation, parameter defaults, return structure, multi-tunnel allowance, and ownership check order, which is sufficient given the presence of an output schema and annotations. It could mention error conditions but overall is solid.
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?
Since schema coverage is 0%, the description compensates by explaining that local_port=0 auto-assigns a free port, and that remote_port is the target port on the place. The place parameter's role is implied by 'on a place'.
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 'Open' and resource 'local port-forward tunnel' targeting a place, distinguishing it from sibling tools like forward_remote_open (remote forwarding), forward_list (listing), and forward_close (closing).
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 usage for creating local port-forward tunnels and notes that multiple tunnels per place are allowed, but it does not explicitly state when to use this tool over alternatives like forward_remote_open, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds beyond this by explaining resource_name selection semantics and the echo-back behavior in the result. This provides useful context about how the tool behaves with optional parameters, which is not covered by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Every sentence adds meaningful information: the first states the function, the second details parameter behavior. No filler or repetition of schema details, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return values. It covers the essential operational context (acquired place, optional resource selection, echo behavior). It does not explicitly state prerequisites like 'must acquire first', but 'for an acquired place' strongly implies this, and sibling tools like acquire_place provide surrounding context. Slightly more detail about output structure or error cases would fully round it out, but it is otherwise complete.
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 description coverage is 0%, so the description must carry the full burden. It explains resource_name thoroughly: that it selects among same-class resources, can be omitted for single-IO-resource places, and is echoed back only when given. For place, it indicates it must be an acquired place. This compensates well for the lack of schema descriptions, though place could be more explicitly described.
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 returns the current digital IO state of an acquired place, with an explicit reference to HttpDigitalOutputDriver.get(). It distinguishes from sibling tools like set_io (which writes) and get_power_state (which reads power) by specifying the exact resource type and operation.
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 usage context by specifying 'for an acquired place' and explains how to use the optional resource_name parameter with a fallback for single-IO-resource places. However, it does not explicitly compare against alternatives or state when not to use it, so guidance is present but not exhaustive.
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?
Annotations already indicate destructive and non-idempotent behavior. The description adds useful behavioral context, such as the requirement that the place must have been acquired by this session and that an invalid 'user' format raises before any RPC. This goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the core purpose, and includes a necessary validation note. 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, the presence of an output schema, and annotations covering destructive behavior, the description adequately covers the purpose, precondition, and validation. It does not elaborate on side effects, but those are already implied by the annotations.
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 schema has 0% description coverage, so the description carries the burden. It explains that 'user' must be in 'host/user' format and implicitly identifies 'name' as the place identifier. This adds meaningful interpretation beyond the bare parameter names.
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 'Allow another user to use a place this session has acquired', which specifies the action (allow), the resource (place), and a key precondition (session has acquired). It distinguishes from siblings like acquire_place and release_place.
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 this tool, namely only for places already acquired by this session. It also specifies the required format for the 'user' parameter. However, it does not explicitly mention alternatives or exclusions, but the context is clear.
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?
Annotations already signal destructive intent. The description adds value by disclosing the side effect of stopping the keepalive task, which is not evident from annotations alone. This gives useful behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It immediately states the action and key qualifier, making it highly efficient.
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, the presence of an output schema, and annotations covering destructive behavior, the description covers the essential use case and side effects. It could mention irreversibility explicitly, but the destructive hint already implies that.
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?
With only one parameter and schema description coverage at 0%, the description compensates by clarifying that 'token' is the identifier used to cancel the reservation. It lacks format or origin details, but for a single string this is largely 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 uses the specific verb 'cancel' with a clear resource ('reservation') and identifier ('by token'). This distinguishes it from sibling tools like 'reserve' or 'list_reservations', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool when you have a reservation token and want to end that reservation. However, it does not explicitly mention when not to use it (e.g., for releasing a place), nor does it name alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds significant behavioral context: it consumes the drained bytes, resets the truncated flag, and handles errored readers by surfacing buffered data alongside failure. These details go beyond annotations and help the agent predict side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences, front-loaded with the primary action. Every sentence adds value—the first states the operation and parameter, the second covers side effects and error behavior. No redundant or filler 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 the tool's simplicity and the presence of an output schema, the description adequately covers the core behavior, parameter meaning, and error conditions. It does not explicitly address when to use it relative to siblings, but that gap is partially covered by the purpose clarity. Overall, it is sufficiently complete for a read/drain operation.
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 description coverage is 0%, so the description must compensate. It explains max_bytes ('up to max_bytes (default all)') and clarifies that null means all. Session is indirectly described via 'unknown session is a tool error', implying it must reference an existing session. This adds meaning beyond the raw schema, though session semantics could be more explicit.
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: 'Drain up to ``max_bytes`` (default all) buffered console bytes.' This uses a specific verb (drain) and resource (buffered console bytes), distinctly distinguishing it from sibling tools like console_send (which writes) and console_open/close (which manage the session).
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 usage (reading console output) but does not explicitly state when to use this tool instead of alternatives like console_send or console_close. It mentions error cases ('unknown session is a tool error') which provides some context, but no direct 'use this when...' guidance or exclusion of other 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?
Annotations only say readOnlyHint false, idempotentHint false, destructiveHint false. The description adds substantial context: the reservation is kept alive in the background, can be cancelled, expires, or invalidated, and returns the serialized reservation with a token. This goes beyond annotations and is crucial for an agent to understand the tool's behavior. No contradiction.
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 two sentences, front-loaded with the action 'Create a reservation', and contains zero filler. Every clause adds meaningful information about lifecycle and return 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?
The description is complete for a create operation: it covers the action, inputs, lifecycle, and return value. The output schema exists, so return details are handled there. It could mention the cancel mechanism more explicitly, but the sibling list includes cancel_reservation, implying the connection.
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?
With 0% schema description coverage, the description names 'filters/priority' but does not explain the meaning of filter keys or priority values beyond what the schema types indicate. It adds some context that these are inputs to the reservation, but leaves ambiguity about their semantic roles.
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 creates a reservation with filters/priority and keeps it alive in the background, distinguishing it from sibling tools like cancel_reservation and list_reservations. The verb 'Create' plus resource 'reservation' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context that this is for creating a reservation, but does not explicitly mention when to use it over alternatives like acquire_place or list_reservations. The lifecycle hints (cancelled, expires, invalidated) imply use cases but no exclusions or alternative tool names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses non-obvious behavioral traits beyond annotations: the comment is 'unvalidated by the coordinator' and the tool 'refuses if the place is acquired by a DIFFERENT identity unless force=True.' These details explain failure modes and the force parameter's purpose, adding meaningful context beyond the destructiveHint annotation. The annotation and description are consistent (no contradiction).
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 two sentences, front-loaded with the primary purpose and followed by a single, relevant caveat. There is no redundant filler or repetition of schema/annotation information. Every word 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 mutation tool with an output schema and annotations already covering destructive behavior, the description covers the essential context: what, when, and a key conditional failure. It does not mention that the comment is overwritten (implied by 'set') or other edge cases, but the information provided is sufficient for an agent to invoke the tool correctly in most scenarios.
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?
Although schema description coverage is 0%, the description gives semantic meaning to all three parameters: 'place' is the existing place, 'comment' is the free-form comment, and 'force=True' is explicitly referenced as the override for different-identity refusals. This compensates for the lack of schema descriptions, especially for the force parameter.
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: 'Set an existing place's free-form comment.' This is a specific verb+resource, and the mention of 'unvalidated by the coordinator' adds nuance that distinguishes it from other place-modification tools like set_place_tags. It is immediately clear what the tool does.
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 the tool is used (setting a comment on a place) and includes an important caveat that it refuses when the place is acquired by a different identity unless force=True. It does not explicitly mention alternatives, but the refusal condition serves as a practical usage guideline by warning when force may be necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it explains the validation trap, rename's non-identity role, refusal under different identity, and the force override. These are critical behavioral details not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds operational value, but some implementation-specific references (labgrid 26.0, design §11.12) are niche and slightly lengthen the text. The structure is clear: purpose, pattern, rename, refusal.
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?
The description covers all key parameters, preconditions, validation, and unusual behavior. Given the four-parameter schema with no descriptions and the presence of an output schema, the description is sufficiently complete for reliable 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?
With zero schema descriptions, the description carries the burden. It thoroughly explains pattern format, rename semantics, and force behavior. Only 'place' is not deeply explained, but its meaning as an existing place identifier is clear from context.
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 'Add a resource match to an existing place,' a specific verb+resource that clearly states the action. The pattern and rename details further distinguish it from sibling tools like add_place and add_place_alias.
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 makes the use case clear and provides conditions like force behavior and pattern arity, but it does not explicitly contrast with alternatives or say when not to use this tool. Usage guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses useful behavior: the newline appending when newline=True and the tool error condition for invalid sessions. It aligns with destructiveHint and does not contradict annotations, though it does not elaborate on side effects beyond signaling a write 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?
The description is two concise sentences, front-loaded with the core action. Every sentence adds value: the first states the primary purpose, and the second covers important behavioral details without 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?
Given the tool's simplicity, the existing annotations, and an output schema, the description is complete. It covers the write action, the newline behavior, and the key error condition, leaving no significant gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the data payload, the newline flag's effect, and session validity. It does not give an explicit definition for the session property, but the open-session framing and error condition add enough meaning for an agent to infer its role.
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 'Write data to an open console session' with a specific verb and resource, making the tool's function immediately clear. It also distinguishes itself from siblings like console_read and console_close by focusing on the write 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 clearly indicates the tool must be used with an open session and that unknown, closed, or errored sessions are errors. It does not explicitly name alternatives or exclusions, but the sibling tools and the phrase 'open console session' imply the intended usage context well.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by specifying the exact return values and noting that the coordinator version is currently null, which aids in interpreting results.
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 a clear front-loaded action. The bullet-like list of return values is efficient and every sentence earns its place.
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, parameterless read-only tool with an output schema and informative annotations, the description fully covers the return values and purpose. 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?
The tool has zero parameters, so description has nothing to add. Baseline of 4 for parameterless tools is appropriate.
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 a specific verb 'Report' and identifies the resource 'coordinator connection', clearly stating what the tool does. It also enumerates the returned fields, distinguishing it from sibling tools that focus on places/reservations/IO.
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 context is clear: use this tool to obtain coordinator connection details. No explicit exclusions or alternatives are given, but none are necessary since no sibling tool covers coordinator connection information.
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?
Beyond the annotations declaring this destructive, the description adds critical behavior: pre-validation against the snapshot to avoid a known coordinator KeyError, the resulting clean error, zero RPCs on typo, and the force override for ownership conflicts. This gives the agent a precise understanding of side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a direct one-sentence purpose, then adds a detailed rationale for pre-validation and the force condition. While the internal reference 'design §11.12 trap' is potentially noisy, every sentence adds actionable information, so it's efficient but slightly verbose.
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?
The description covers error handling, preconditions, and ownership rules, while the output schema presumably documents the success response. It does not explicitly address reversibility or broader side effects, but destructiveHint and the removal semantics suffice given the annotations.
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?
With 0% schema description coverage, the description compensates by documenting the alias removal operation and explaining force as a bypass for ownership restrictions. However, the 'place' parameter is only implied by context ('existing place') and no format or validation details are given, leaving some gap.
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 opening sentence 'Remove an alias from an existing place' uses a specific verb and resource, clearly distinguishing it from sibling add_place_alias. Even without reading the rest, the tool's function is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual conditions: it pre-validates the alias before RPC and requires force=True when the place is acquired by a different identity. However, it does not explicitly contrast with add_place_alias or other sibling tools, so it lacks an explicit alternative recommendation, though the opposite operation is obvious.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context about the 'live' state and the underlying session source (forwards.sessions()), without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, scope, and source without any 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?
With zero parameters, an output schema present, and strong read-only annotations, the description fully covers what is needed for this simple list operation. It states the action, scope, and underlying method.
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, and schema coverage is 100%. The description doesn't need to explain parameter semantics, so the baseline of 4 applies.
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 the specific verb 'List' with the resource 'live forward tunnels' and scope 'across every place'. It clearly distinguishes from sibling tools like forward_open/forward_close (which modify tunnels) and list_places (which lists places rather than tunnels).
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: this is for listing all live forward tunnels globally. It doesn't explicitly name alternatives, but no alternative listing tool exists among siblings, so the context is sufficient to indicate when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint:false, destructiveHint:false. The description adds valuable behavioral details: it writes a local file (non-destructive to DUT), refuses existing local target unless overwrite=True (pinned ToolError), and requires parent directory to exist. It also specifies the return structure, exceeding what annotations offer.
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 four sentences, each adding value. It front-loads the core purpose, then details constraints and return type. Slightly verbose with the 'NOT read-only' clause, but that nuance is useful given annotations. No 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?
The description covers prerequisites (acquired place, parent directory exists), conditional behavior (overwrite), return format, and non-destructive characterization. For a file-copy tool, it is complete and self-sufficient even without the 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?
With 0% schema description coverage, the description compensates fully: it explains place (as 'acquired place'), remote_path (source), local_path (target), and overwrite behavior. Each parameter's role is made clear, and the overwrite default behavior is described.
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 'Copy remote_path from an acquired place to local_path (scp)', a specific verb+resource pair. It distinguishes from sibling tools like put_file (which does the reverse). The scp analogy and 'acquired place' clarify the context.
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 usage by explaining the copy direction and prerequisites (acquired place, parent directory must exist), but it does not explicitly discuss alternatives or when not to use this tool. No exclusions or comparison with siblings beyond the scp hint.
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?
Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the tool only works for an acquired place (implying a prerequisite) and that USB mux has no read method, which explains a limitation not evident from annotations alone. This is more than what the HIGH calibration example provided, so a 4 is warranted.
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 to the point, with the core purpose in the first line and a clarifying scope note in the second. Every sentence earns its place, and the structure is front-loaded with the most important information. 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?
This is a simple getter with one parameter, strong annotations (read-only, idempotent, non-destructive), and an output schema. The description covers the essential information: what it retrieves, the prerequisite (acquired place), and the limitation (SD-mux only). Since the output schema exists to define return values, the description is sufficiently complete for an agent to correctly invoke the tool.
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?
The input schema has one `place` parameter with zero description coverage. The description only indirectly refers to it via 'for an acquired place,' implying the parameter identifies a previously acquired place. This adds some meaning but does not explain the format, valid values, or how it relates to the broader system. Given the low schema coverage, the description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates that the tool retrieves the current SD-mux mode for an acquired place, referencing the underlying `USBSDMuxDriver.get_mode()` method. It also distinguishes itself from any USB mux counterpart by explicitly stating there is no equivalent, making the tool's specific scope 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 explicitly states that this tool is for SD-mux only (§11.14) and that the `LXAUSBMuxDriver` (usb_mux) has no read method, so there is no `usb_mux` equivalent. This directly tells the agent when to use this tool versus alternatives and prevents incorrect attempts with the USB mux kind.
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?
Annotations already indicate destructive and non-idempotent behavior; the description adds a pinned ToolError for missing local files before driver binding and specifies the return fields. This goes beyond the annotations by disclosing an error precondition and operation result shape, with no contradiction.
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 tightly written sentences, with the core purpose front-loaded and no filler. The first sentence states the action, the second adds error behavior and return shape, making every word earn its place.
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 3-parameter copy tool with output schema and annotations already present, the description covers the transfer mechanism, the precondition, and the return semantics. Combined with the structured data, it is sufficiently complete for an agent to select and invoke 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?
With 0% schema description coverage, the description carries the parameter-semantics burden. It clarifies place as 'an acquired place', local_path as a local file that must exist, and remote_path as the destination, plus notes that 'bytes' is the local file size. It doesn't specify path formats or place identifiers, but it provides functional meaning for all three 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 opens with a specific verb phrase: 'Copy a local file to remote_path on an acquired place (scp)', clearly identifying action, resource, and method. It distinguishes itself from siblings like get_file (reverse direction) and ssh_run (command execution) by naming the scp transfer behavior.
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 states the context 'on an acquired place', implying a prerequisite that the place must be acquired before calling, and 'scp' signals network file transfer. It does not explicitly name alternatives or when-not-to-use, so it falls short of the highest bar, but the context is clear.
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?
Annotations already mark it as destructive, but the description adds valuable context: it verifies current holder by default and allows unconditional release with kick. This goes beyond the basic destructive hint without contradicting it.
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 two sentences, front-loaded with the main action, and the second sentence adds the only necessary behavioral nuance. 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, the presence of an output schema, and annotations, the description covers the essential action and parameters. It could mention error conditions or the inverse relationship with acquire_place, but it is complete enough for confident use.
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%, so the description must explain parameters. It does: 'by name' clarifies the 'name' parameter, and 'kick=True' explains the 'kick' boolean. 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 specific action 'Release a place by name', which is a distinctive verb+resource combination. It differentiates from siblings like acquire_place (opposite) and release_from (different release target) by focusing on releasing a place itself.
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 provides clear context on when to use the default behavior vs kick=True (force release regardless of holder). However, it does not explicitly mention alternatives like release_from or when not to use this tool, so it lacks explicit 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?
Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses concrete side effects: it binds a raw-protocol SerialDriver, starts a background reader, enforces one session per place via a registry, and runs the ownership check before any registry call. This is meaningful behavioral detail that annotations alone do not provide.
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 front-loaded: the main purpose is stated first, followed by behavioral details and the ownership-check ordering. The internal reference 'console.py, DESIGN §11.10' is mildly noisy for an agent but does not significantly detract from 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 single parameter, an output schema, and sibling tools for acquisition and console I/O, the description is complete. It covers the purpose, preconditions (acquired place), exclusivity (one session per place), and failure mode (second open rejected). An agent has enough context to decide when and how to invoke the 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?
The schema only provides a required 'place' string with no description coverage. The tool description compensates by clarifying that the place must be an acquired place and that ownership is checked. It does not specify the exact identifier format, but the combination of the schema and description gives enough semantic meaning for the parameter.
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 and resource: 'Open an interactive console session on an acquired place.' It clearly distinguishes itself from sibling console tools (console_read, console_send, console_close) by being the session-establishing operation, and the one-session-per-place rule further defines its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: on an acquired place, before console I/O, and only if no session is already open. It also warns that a second open is rejected. It does not explicitly name alternatives or say 'use console_read after this,' but the context is strong enough for an agent to infer the correct workflow.
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?
Annotations are minimal (readOnlyHint=false, idempotentHint=false, destructiveHint=false) and provide little safety info. The description adds valuable behavioral context: it explains the direction semantics, the requirement that a local service must already be listening, the ownership check ordering, and the return payload shape. The only unaddressed aspect is detailed error behavior, but the provided behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise for the complexity it covers. It front-loads the primary purpose in the first line and packs essential behavioral details into a compact paragraph. Some could argue the sentence about forward_list/forward_close is a bit tangential, but it adds useful context for understanding how this tool relates to siblings.
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 (SSH port forwarding with direction semantics, ownership check ordering, relation to sibling forward tools), the description covers the essential aspects: what it does, when to use it, the required preconditions, return payload, and cross-tool consistency. The output schema exists, so return value documentation is adequately handled. This is a complete description for a moderately complex 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?
Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It explains what both ports mean in the forwarding direction: a connection to remote_port on the DUT is forwarded to localhost:local_port on this host. It also states that the local service must already be listening, which is critical parameter context 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?
The description opens with a specific verb+resource: "Open a REMOTE (-R) port-forward tunnel on a place." It clearly distinguishes this from forward_open by noting the local (-L) alternative and explains the required remote_port and local_port semantics. This is a specific, unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with forward_open's local forward, explains that both ports are required because labgrid's SSHDriver has no auto-assign, and notes that a local service must already be listening. It also mentions that forward_list/forward_close work identically regardless of direction, providing clear context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent, but the description adds valuable behavioral details: it is gated because it talks to a real hardware path, resource_name selection semantics, and the exact error condition for multi-resource places. Also explains the additive echo behavior in the result. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence adds value, covering purpose, implementation, gating, resource_name edge cases, and result behavior. The internal reference (§11.14) is a minor obstacle but does not hurt overall 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 presence of an output schema and annotations for safety, the description covers the tool's purpose, usage context, resource_name edge cases, and result echo behavior. It is complete for a read tool with these structured fields.
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 description coverage is 0%, so the description must compensate. It fully explains resource_name (omit for single-resource, error naming available resources on multi-resource) and implies place must be an acquired place. The place parameter is not as explicitly described, but it is straightforward.
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 returns the current power state for an acquired place, with a specific verb and resource. It distinguishes this read tool from siblings by noting it is gated because it accesses real hardware, unlike always-on Phase 1/2 read 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?
Provides context on when to use this tool (reads via NetworkPowerDriver) and clarifies that it is gated unlike other read tools. It also gives specific guidance on resource_name: omit for single-power-resource places, and warns that an unnamed pick on multi-resource places is an error. It does not explicitly name alternative tools but the context 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?
Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description reveals the acquisition process: direct acquisition for free places, name-filtered reservation for taken/reserved ones, polling bounded by config.acquire_timeout, reservation drop, and error behavior on RPC failure or timeout. This is substantial additional 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 two sentences: the first is a crisp front-loaded summary, the second elaborates the process and error handling. There is no fluff; every sentence adds technical value. It is appropriately sized.
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 (potential polling, timeout, reservation lifecycle) and the presence of an output schema, the description is thorough. It covers the acquisition path, timeout bounds, reservation cleanup, and error handling, which is sufficient for an agent to anticipate behavior.
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?
With schema coverage at 0%, the description compensates by identifying the sole parameter 'name' as the place name to acquire. It doesn't specify format or validation rules, but the meaning is clear from the opening sentence, and no other parameters exist.
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: 'Acquire a place by name for this session.' It uses a specific verb and resource, and distinguishes from sibling tools like list_places and release_place by focusing on acquisition. The additional detail about free vs. taken places further clarifies its unique role.
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: it's used to acquire a place for the current session, with specific behavior for free vs. taken places. It doesn't explicitly compare to sibling tools like reserve or show_place, but the session-scoped acquisition purpose is clear enough to imply when to use it, without stating 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?
The description discloses significant behavioral details beyond the annotations: timeout_s is clamped to 25.0, polling keeps TTL alive for waiting/allocated reservations, dead tokens or timeouts return changed=False without raising, and the tool is non-destructive but not idempotent. These details are consistent with the annotations (false for readOnly/idempotent/destructive) and add 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?
The description is dense but every sentence adds critical information: purpose, timeout clamp, TTL mechanics, return semantics, and error behavior. It is front-loaded with the purpose and uses a structured format with clear conditional clauses.
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, the description covers the purpose, usage, timing semantics, return values (including edge cases like dead tokens), and follow-up actions. The output schema exists and the description supplements it with behavioral context, making it a complete guide for an agent.
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?
Despite 0% schema description coverage, the description explains the timeout_s parameter's clamping behavior and its implications, and the return behavior distinguishes timeouts from allocation. The token parameter is self-explanatory, so the description adds meaningful semantics for the parameters that need it.
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: 'Block-and-poll a reservation until it allocates a place, or times out.' It identifies the resource (reservation) and the action (wait/poll), distinguishing it from other reservation tools like reserve or acquire_place.
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 on how to use the tool, noting the timeout clamp and the need to call acquire_place (or another reservation_wait/cancel_reservation) soon after it returns. However, it does not explicitly list alternatives or state when not to use it beyond the immediate follow-up, so it doesn't fully meet the 'explicit when/when-not/alternatives' standard.
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?
Annotations already indicate destructive write (destructiveHint=true, readOnlyHint=false). The description adds detail about error handling, delay-only-for-cycle, resource_name selection, and ownership check, enriching the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and structured, but §11.14 references are cryptic and error handling is repeated. Still, each 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?
With annotation and output schema existing, description covers all critical parameter semantics and behavioral rules; return value is handled by output schema. It explains prerequisites and error paths.
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% coverage, so description compensates fully: action values enumerated, delay semantics and constraints, resource_name behavior, and place context (acquired).
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 drives power on/off/cycle on an acquired place and returns the resulting state. It uses a specific verb+resource and distinguishes from sibling read-only get_power_state and other set_* 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?
It implies usage on an acquired place and describes validation of action, but doesn't explicitly contrast with get_power_state or other alternatives. The ownership requirement is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations, detailing timeout semantics (inner and outer enforcement), the lack of remote process termination on timeout, and labgrid's whitespace-splitting behavior. It also explains the return format (stdout/stderr as line lists joined with newlines). This provides deep behavioral transparency with no contradiction to annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence is informative; caveats about timeouts and quoting are essential. The internal references (target.py, §11.13) add some noise, but the structure is logical and front-loaded with purpose.
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 the tool's complexity and the lack of an output schema, the description covers return values, timeout behavior, edge cases, and the execution mechanism. It is complete enough for an agent to use the tool correctly without additional context.
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 schema coverage at 0%, the description compensates thoroughly: it explains 'command' and the whitespace-splitting caveat, details how 'timeout_s' is enforced (including the +5.0s grace period), and clarifies that 'place' must be an acquired place. This adds meaning far beyond the bare parameter names and types.
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 'Run command over SSH on an acquired place and return its result,' which clearly states the action, resource, and output. This distinguishes it from sibling tools like console_* (serial) and put_file/get_file (file transfer), giving it a specific identity.
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 clearly indicates the tool is for executing commands over SSH on an acquired place, providing strong contextual cues for when to use it. It does not explicitly name alternatives or exclusions, but the context is specific enough to guide selection among siblings.
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?
Goes far beyond annotations: explains the long-poll mechanics, timeout clamping to 25.0, the orphaned poll behavior, process-local cursor resets on restart, and stale cursor self-healing. Adds substantial behavioral context the annotations do not cover.
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 long but well-structured and front-loaded with the core purpose. Every paragraph adds critical usage or behavioral detail. Slightly verbose but appropriate for a tool with this 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, output schema presence, and annotations, the description is remarkably complete. It covers edge cases (server restart, stale cursors, client timeouts), usage patterns, and safety properties, leaving no meaningful gaps 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?
Schema description coverage is 0%, but the description fully explains both parameters: cursor's role as a bootstrap/checkpoint and timeout_s's clamping behavior. This adds essential meaning beyond the raw schema fields.
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: 'Long-poll for the next place/resource change' – a specific verb+resource. It distinguishes itself from siblings by positioning as 'the live-monitor substitute' with no subscription surface, and explains the cursor-based polling pattern.
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?
Provides explicit usage guidance: bootstrap with cursor=None, then pass returned cursor on subsequent calls; explains blocking behavior and timeout. It gives clear context for when to use (monitoring changes) but does not explicitly name alternatives or exclusions, though the 'live-monitor substitute' phrase implies contrast with snapshot 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?
The description discloses critical behavioral traps beyond the annotations: the coordinator's silent no-op on fromuser mismatch, the unreliability of a post-call check, the need to compare snapshots, and the validation performed before the RPC. It also explains the direct coordinator path, all reinforcing the destructiveHint and providing context annotations alone cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Despite its length, every sentence adds essential value: the contrast with release_place, the silent no-op trap, the correct verification method, the internal client path, and validation rules. The description is front-loaded with a clear summary and logically organized, making it 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all critical aspects: purpose, usage context, behavioral traps, verification methodology, validation requirements, and internal execution path. The output schema handles return value details, so no further elaboration is needed, making it complete for the tool's 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?
With 0% schema coverage, the description compensates by explaining the role of each parameter (place, host/user identity) and the validation requirements (non-empty, '/'-free). While it does not provide exhaustive format details or examples, it gives sufficient semantic meaning 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 first sentence clearly states the action (release) and the target (place, from a specific host/user identity). It explicitly contrasts with release_place, making the purpose unmistakable by distinguishing the arbitrary identity targeting from the sibling's own-acquisition-only 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 the use case (operator clearing a stale/foreign hold) and contrasts with release_place, noting that session.release_place would refuse to release another identity. This provides clear when-to-use guidance and identifies the alternative and why it is unsuitable.
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:

[![labgrid-mcp MCP server](https://glama.ai/mcp/servers/onurcelep/labgrid-mcp/badges/card.svg)](https://glama.ai/mcp/servers/onurcelep/labgrid-mcp)

Score Badge

Copy to your README.md:

[![labgrid-mcp MCP server](https://glama.ai/mcp/servers/onurcelep/labgrid-mcp/badges/score.svg)](https://glama.ai/mcp/servers/onurcelep/labgrid-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/onurcelep/labgrid-mcp'

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