Shell-MCP

by kevinwatt

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Each tool corresponds to a distinct, well-known Unix/Linux command with a clear, non-overlapping purpose. For example, shell_cat is for file display, shell_df for disk usage, and shell_ps for process status, making it easy for an agent to select the right tool without confusion.
Naming Consistency5/5
All tool names follow a consistent 'shell_' prefix followed by the exact command name (e.g., shell_cat, shell_date, shell_df). This uniform pattern enhances readability and predictability across the entire set.
Tool Count4/5
With 20 tools, the server covers a broad range of system utilities, which is reasonable for a shell command interface. It might be slightly heavy, but each tool is a standard command, so the count aligns well with the server's purpose of providing comprehensive shell access.
Completeness5/5
The tool set offers extensive coverage of common Unix/Linux commands for file operations, system monitoring, network tasks, and process management. There are no obvious gaps for a shell utility server, as it includes essential tools like ls, grep, ps, and networking commands, ensuring agents can handle typical tasks without dead ends.
Average 2.9/5 across 20 of 20 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Show disk usage' implies a read-only operation, but it doesn't specify output format, potential side effects, or error conditions. For a shell command tool with no annotations, this leaves critical behavioral traits undocumented, such as how it interacts with the system or what permissions might be required.
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 very concise with just three words, making it front-loaded and efficient. However, it's arguably too brief, bordering on under-specification, which slightly reduces its effectiveness. Every word earns its place, but more detail could improve clarity without sacrificing conciseness.
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 the complexity of a shell command tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, how to interpret results, or any dependencies. For a tool that likely outputs structured disk usage data, this lack of context makes it inadequate for an AI agent to use correctly without additional assumptions.
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 100% description coverage, with one parameter 'args' described as 'Command arguments'. The description adds no additional meaning beyond this, as it doesn't explain what arguments are valid or provide examples. With high schema coverage, the baseline score of 3 is appropriate, but the description doesn't compensate with any extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show disk usage' states the tool's purpose but is vague about what specific resource it operates on. It distinguishes from siblings like 'shell_cat' or 'shell_ps' by focusing on disk usage, but lacks specificity about whether it shows usage for filesystems, partitions, or directories. It's not tautological but could be more precise.
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 alternatives. It doesn't mention any context, prerequisites, or exclusions, and there's no reference to sibling tools for comparison. Users must infer usage from the name alone, which is insufficient for effective 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'show / manipulate' but doesn't specify whether this requires elevated permissions, what 'manipulate' entails (e.g., destructive changes), or any rate limits or side effects. The description is too brief to provide meaningful behavioral context for a tool that could involve network configuration.
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, efficient sentence: 'Show / manipulate routing, network devices, interfaces and tunnels'. It's front-loaded and wastes no words, making it easy to scan. However, it could be more structured by separating show vs. manipulate functions, but it's appropriately sized for its content.
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 the complexity of network tools and the lack of annotations and output schema, the description is incomplete. It doesn't explain return values, error conditions, or provide context for the 'manipulate' aspect, which could involve risky operations. For a tool with potential destructive behavior and no structured support, more detail is needed to guide safe usage.
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 100% description coverage, with one parameter 'args' described as 'Command arguments'. The description adds no additional meaning beyond this, as it doesn't explain what types of arguments are expected or provide examples. With high schema coverage, the baseline is 3, but the description doesn't compensate with any param-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool is for 'Show / manipulate routing, network devices, interfaces and tunnels', which provides a general purpose but is vague about the specific verb and resource. It mentions 'show' and 'manipulate' as actions but doesn't specify how these relate to the 'shell_ip' name or distinguish it from sibling network tools like shell_netstat or shell_nslookup. The purpose is understandable but lacks precision.
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 offers no guidance on when to use this tool versus alternatives. With sibling tools like shell_netstat for network statistics and shell_nslookup for DNS queries, there's no indication of when shell_ip is appropriate, such as for IP routing configuration or network interface management. No exclusions or prerequisites are mentioned, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the tool's function as a DNS lookup utility, without detailing what it does (e.g., returns records, resolves IPs), potential side effects, error handling, or output format. This leaves significant gaps in understanding the tool's behavior beyond its basic purpose.
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 extremely concise with just three words, 'DNS lookup utility', which is front-loaded and wastes no space. It directly states the tool's purpose without unnecessary elaboration, making it efficient and easy to parse.
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 the complexity of a DNS lookup tool with no annotations and no output schema, the description is incomplete. It fails to explain what the tool returns, how to interpret results, or any behavioral nuances. For a tool that likely involves network queries and parameterized arguments, more context is needed to ensure proper usage by an AI 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?
The input schema has 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description does not add any meaning beyond this, such as examples of common arguments or their effects. Since schema coverage is high, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'DNS lookup utility' clearly states the tool's function (DNS lookup) but is vague about the specific action (e.g., querying records, resolving names) and does not distinguish it from sibling tools like 'shell_nslookup' or 'shell_whois', which likely serve similar DNS-related purposes. It provides a general category rather than a specific verb+resource combination.
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 offers no guidance on when to use this tool versus alternatives such as 'shell_nslookup' or 'shell_whois', nor does it mention any context, prerequisites, or exclusions. It lacks any usage instructions, leaving the agent to infer based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Display text' without disclosing behavioral traits like output format, side effects, or how it interacts with the shell. It's minimal and doesn't add meaningful context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two words, front-loaded and zero waste. It's appropriately sized for a simple tool, though this conciseness contributes to vagueness in other dimensions.
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 no annotations, no output schema, and a simple tool, the description is incomplete. It doesn't explain what 'Display text' means in practice, return values, or how it fits with siblings, leaving gaps for agent understanding.
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 description coverage is 100%, so the schema documents the 'args' parameter well. The description adds no parameter semantics beyond what's in the schema, meeting the baseline for high coverage but not compensating with extra details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Display text' states a basic purpose (verb+action) but is vague about what 'text' refers to and doesn't distinguish from siblings like shell_cat or shell_echo. It's better than a tautology but lacks specificity about the shell echo command's exact function.
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 on when to use this tool versus alternatives is provided. The description doesn't mention context, prerequisites, or comparisons to siblings like shell_cat for file output or shell_echo for command-line echoing, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool searches text patterns in files, implying a read-only operation, but does not cover critical aspects like error handling (e.g., if files are missing), performance implications (e.g., for large files), or output format. This leaves significant gaps in understanding how the tool behaves beyond its basic purpose.
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 extremely concise with a single phrase, 'Search text patterns in files', which is front-loaded and wastes no words. It efficiently conveys the core purpose without unnecessary elaboration, making it easy for an agent to parse quickly.
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 the tool's complexity (a shell command with one parameter), lack of annotations, and no output schema, the description is incomplete. It does not explain what the tool returns (e.g., matched lines, file names), error conditions, or how it interacts with the system. For a tool that could have varied behavior based on arguments, more context is needed to guide effective use.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description does not add any meaning beyond this, such as examples of typical arguments (e.g., patterns, file paths) or syntax details. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search text patterns in files' clearly states the tool's function with a specific verb ('search') and resource ('text patterns in files'), avoiding tautology. However, it does not distinguish this tool from potential siblings like 'shell_find' (which might also search files) or clarify that it uses grep-like functionality, leaving some ambiguity in its exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 alternatives. It does not mention sibling tools like 'shell_find' or 'shell_cat' that might overlap in functionality, nor does it specify contexts such as searching within file contents versus metadata. Without any usage instructions, the agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'List directory contents' implies a read-only operation, but it doesn't specify permissions needed, output format (e.g., list vs. detailed), error handling, or system-specific behaviors (e.g., hidden files). This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient phrase: 'List directory contents'. It's front-loaded with the core action and resource, with zero wasted words, making it highly concise and well-structured for quick understanding.
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 the complexity (a shell command tool with no annotations and no output schema), the description is incomplete. It lacks details on behavioral traits, output expectations, and usage context relative to siblings. For a tool that interacts with the file system, more information is needed to guide effective use by an AI 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?
The input schema has 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description doesn't add any meaning beyond this, such as examples of common arguments (e.g., '-l' for long format). Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't compensate but doesn't detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List directory contents' clearly states the tool's function with a specific verb ('List') and resource ('directory contents'), avoiding tautology. However, it doesn't distinguish this tool from its siblings (e.g., shell_find, shell_whereis) which also deal with file system exploration, making it somewhat vague in context.
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 alternatives. It doesn't mention scenarios like checking file existence, exploring directories, or how it differs from siblings like shell_find for searching or shell_pwd for current directory, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It doesn't specify if this is a read-only operation, what permissions are required, how output is formatted, or potential side effects. The description is too brief to adequately inform the agent about behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just three words, with zero wasted text. It is front-loaded and efficiently communicates the core purpose without unnecessary elaboration, making it easy for an agent to parse quickly.
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 the complexity of a shell command tool with no annotations, no output schema, and minimal description, the description is incomplete. It doesn't explain what 'netstat' does specifically, what information is returned, or how to interpret results, leaving significant gaps for an agent to use the tool effectively.
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 schema description coverage is 100%, with the single parameter 'args' documented as 'Command arguments'. The description adds no additional meaning about parameters, such as typical argument values or examples. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Network connection information' states what the tool does at a high level but lacks specificity. It doesn't mention the verb (e.g., 'display', 'list', 'show') or differentiate from sibling tools like 'shell_ip' or 'shell_nslookup' that also provide network-related information. The purpose is clear but vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 alternatives. It doesn't mention context, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone among many shell siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Show process status' implies a read-only operation, but it does not specify critical details like output format, potential side effects, error handling, or system dependencies. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just three words, 'Show process status', which efficiently conveys the core purpose without unnecessary elaboration. It is front-loaded and wastes no words, making it easy to parse quickly.
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 the complexity of a shell command tool with no annotations and no output schema, the description is incomplete. It fails to explain what the output looks like, how errors are handled, or any system-specific nuances. This lack of context makes it inadequate for an agent to use the tool effectively without additional information.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description does not add any meaning beyond this, such as examples of valid arguments or their effects. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show process status' clearly indicates the tool's function with a specific verb ('Show') and resource ('process status'), avoiding tautology. However, it does not distinguish this tool from its sibling tools (e.g., shell_ps vs. shell_netstat or shell_w, which also show system status), leaving room for ambiguity in tool selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 alternatives. It lacks context such as prerequisites, typical use cases, or comparisons to sibling tools like shell_netstat or shell_w, which might overlap in functionality. This omission reduces the agent's ability to make informed decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'concatenate and display' implies a read-only operation, it doesn't specify whether this tool requires file permissions, how it handles errors (e.g., missing files), or if it has any side effects like modifying files. For a tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence: 'Concatenate and display file contents'. It's front-loaded with the core purpose, has zero wasted words, and is appropriately sized for a simple tool. Every part of the sentence earns its place by clearly conveying the tool's function.
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 the tool's complexity (a shell command with potential behavioral nuances), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'concatenate and display' entails operationally (e.g., output format, error handling, or interaction with the shell environment), leaving gaps that could hinder an agent's ability to use it correctly.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description doesn't add any meaningful details about parameter usage beyond what the schema provides, such as examples of typical arguments (e.g., file paths). Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the heavy lifting.
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 'Concatenate and display file contents' clearly states the tool's function with a specific verb ('concatenate and display') and resource ('file contents'), making the purpose immediately understandable. However, it doesn't explicitly distinguish this from sibling tools like 'shell_grep' or 'shell_find' which also work with file contents, so it doesn't reach the highest score.
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 alternatives. It doesn't mention when to choose 'shell_cat' over other file-related tools like 'shell_grep' for searching or 'shell_ls' for listing, nor does it specify any prerequisites or exclusions. This leaves the agent with minimal context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'Show' implies a read-only operation, but the description doesn't specify whether this requires special permissions, what format the output takes, whether it's real-time or cached, or any rate limits. For a shell command tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 extremely concise at just three words ('Show system date and time'), with zero wasted language. It's front-loaded with the core purpose and contains no unnecessary elaboration. Every word earns its place in communicating the essential function.
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 the tool's simplicity (single optional parameter, no output schema, no annotations), the description is minimally complete but inadequate. It doesn't explain what 'system' refers to (local vs remote), what format the output will be in, or any behavioral constraints. For a shell command that could have various output formats and behaviors depending on arguments, more context would be helpful despite the tool's basic nature.
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 schema has 100% description coverage, with the 'args' parameter documented as 'Command arguments.' The description adds no additional parameter information beyond what the schema provides. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.
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 'Show system date and time' clearly states the tool's function with a specific verb ('show') and resource ('system date and time'). It distinguishes from siblings like shell_uptime (system uptime) or shell_w (logged-in users), but doesn't explicitly differentiate from all siblings. The purpose is unambiguous but could be more precise about what 'system' means in this context.
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 alternatives. It doesn't mention when this tool is appropriate compared to other date/time tools or system information tools, nor does it specify any prerequisites or contexts where it should or shouldn't be used. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('search') but doesn't cover critical aspects like whether it's read-only, if it requires specific permissions, how results are returned, or potential side effects (e.g., performance impact on large directories). This leaves significant gaps for safe and effective use.
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, clear sentence with no wasted words. It's front-loaded with the core purpose ('Search for files'), making it easy to parse quickly. This efficiency is ideal for tool selection without unnecessary elaboration.
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 the complexity of a shell-based file search tool with no annotations and no output schema, the description is insufficient. It lacks details on behavior, output format, error handling, and usage context, which are crucial for an agent to invoke it correctly. More information is needed to compensate for the missing structured data.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description doesn't add any semantic details beyond this, such as example arguments or formatting rules. Since the schema already provides basic parameter info, the baseline score of 3 is appropriate, but no extra value is contributed.
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 'Search for files in a directory hierarchy' clearly states the verb ('search') and resource ('files in a directory hierarchy'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'shell_ls' or 'shell_whereis', which also deal with file/directory operations, but the specific focus on searching is clear.
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 alternatives. It doesn't mention prerequisites, typical use cases, or comparisons to siblings like 'shell_ls' (list files) or 'shell_grep' (search within files). Without such context, an agent might struggle to choose appropriately among similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Show memory usage' implies a read-only operation, but it doesn't specify what type of memory is shown (e.g., RAM, swap), the output format, any permissions required, or potential side effects. For a tool with no annotation coverage, this is a significant gap in 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 extremely concise with just three words, front-loading the core purpose without any wasted text. Every word earns its place, making it efficient and easy to parse, though this brevity contributes to gaps in other dimensions.
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 the lack of annotations and output schema, the description is incomplete for a tool that likely returns system memory data. It doesn't explain what the tool shows (e.g., free memory, used memory, swap), the format of the output, or any behavioral nuances, leaving the agent with insufficient context to use it effectively.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description doesn't add any meaning beyond this, such as examples of valid arguments or their effects. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema does the heavy lifting for parameter documentation.
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 'Show memory usage' clearly states the tool's function with a specific verb ('Show') and resource ('memory usage'), making its purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'shell_df' (disk usage) or 'shell_ps' (process status), which might also relate to system resource monitoring, so it doesn't reach the highest score.
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 alternatives. It doesn't mention any prerequisites, exclusions, or compare it to sibling tools like 'shell_df' for disk usage or 'shell_ps' for process memory, leaving the agent to infer usage context based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It states what the tool does ('List PCI devices') but doesn't describe how it behaves—such as output format, error handling, permissions required, or whether it's read-only or has side effects. This leaves significant gaps for an agent to understand the tool's 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 extremely concise at just three words ('List PCI devices'), with zero wasted language. It's front-loaded and directly communicates the core function without unnecessary elaboration, making it efficient and easy to parse.
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?
For a tool with no annotations and no output schema, the description is insufficiently complete. It lacks details on behavioral traits, output format, and usage context, which are critical for an agent to invoke it correctly. While the purpose is clear, the overall context needed for effective tool use is missing.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description adds no additional parameter semantics beyond this, as it doesn't explain what arguments are valid or provide examples. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
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 'List PCI devices' clearly states the tool's function with a specific verb ('List') and resource ('PCI devices'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'shell_lsusb' (which lists USB devices), missing an opportunity for full sibling distinction.
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 alternatives. It doesn't mention when to choose 'shell_lspci' over other system information tools like 'shell_ls' or 'shell_lsusb', nor does it specify any prerequisites or exclusions for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'List USB devices' implies a read-only operation but doesn't specify output format, whether it requires special permissions, potential side effects, or how it handles errors. For a shell tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise at three words, front-loaded with the essential information. There's zero waste or unnecessary elaboration, making it immediately scannable and understandable.
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 no annotations, no output schema, and a single parameter with good schema coverage, the description is incomplete. It doesn't address what the tool returns, error conditions, or behavioral characteristics needed for a shell command tool. The minimal description leaves too many questions unanswered.
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 schema has 100% description coverage for its single parameter ('args' with description 'Command arguments'), so the baseline is 3. The tool description doesn't add any parameter-specific information beyond what's in the schema, but doesn't need to compensate for gaps either.
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 'List USB devices' clearly states the verb ('List') and resource ('USB devices'), making the purpose immediately understandable. It distinguishes this tool from siblings like shell_ls (general listing) or shell_lspci (PCI devices), though it doesn't explicitly mention this differentiation.
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 alternatives. There's no mention of prerequisites, when it's appropriate versus other listing tools, or any context about its specific use case beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but only states the basic action ('Query DNS records'). It doesn't mention whether this requires network access, has rate limits, returns structured or raw output, or any error conditions. For a tool with zero annotation coverage, this is inadequate.
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 extremely concise with just three words ('Query DNS records'), front-loading the core purpose without any wasted text. Every word earns its place, making it efficient and easy to parse.
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 the complexity of DNS querying, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what types of DNS records are queried, the output format, error handling, or dependencies. For a tool that likely interacts with external systems, more context is needed.
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 schema description coverage is 100%, with the 'args' parameter fully documented as 'Command arguments'. The description adds no additional parameter semantics beyond what the schema provides, such as example arguments or formatting details. Given the high schema coverage, the baseline score of 3 is appropriate.
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 'Query DNS records' clearly states the tool's purpose with a specific verb ('Query') and resource ('DNS records'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'shell_dig' or 'shell_whois' which also perform DNS-related operations, preventing a perfect score.
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 alternatives like 'shell_dig' or 'shell_whois' from the sibling list. It lacks any context about specific use cases, prerequisites, or exclusions, leaving the agent with no usage direction beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool's action but does not describe any behavioral traits such as output format, side effects, error handling, or system impact. For a shell command tool with no annotations, this is a significant gap in 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 a single, clear sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and efficiently conveys the essential information, making it highly concise and well-structured.
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 the lack of annotations and output schema, the description is incomplete. It does not explain what the tool returns, how it behaves, or any contextual details needed for effective use. For a shell tool with potential system interactions, more information is required to ensure the agent can use it correctly.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments.' The description does not add any meaning beyond this, as it mentions no parameters. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
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 clearly states the tool's function: 'Show who is logged on and what they are doing.' It specifies the verb ('show') and resource ('who is logged on'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'shell_whois' or 'shell_ps', which might have overlapping or related functionality, preventing a perfect score.
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 alternatives. It does not mention any context, prerequisites, or exclusions, nor does it refer to sibling tools. This lack of usage instructions leaves the agent without direction on appropriate scenarios for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool queries WHOIS information but doesn't describe what happens during execution (e.g., network calls, rate limits, error handling, or output format). For a tool that likely makes external requests, this lack of transparency is a significant gap.
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, efficient sentence with zero waste. It's front-loaded with the core purpose and avoids unnecessary elaboration. Every word earns its place, making it highly concise and well-structured for quick understanding.
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 the tool's complexity (likely involving external WHOIS queries) and the absence of annotations and output schema, the description is incomplete. It doesn't cover behavioral aspects like network dependencies, error cases, or result formatting. For a tool in a shell environment with potential execution nuances, more context is needed to guide the agent effectively.
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 100% description coverage, with the 'args' parameter documented as 'Command arguments'. The description doesn't add any parameter-specific details beyond what the schema provides, such as example arguments or formatting. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
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 clearly states the tool's purpose as 'Query WHOIS domain registration information', which specifies the verb ('query') and resource ('WHOIS domain registration information'). It distinguishes itself from sibling tools like shell_dig or shell_nslookup by focusing on WHOIS queries rather than DNS resolution. However, it doesn't explicitly differentiate from all siblings beyond the domain-specific context.
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 alternatives. It doesn't mention prerequisites, typical use cases, or comparisons to similar tools like shell_dig for DNS queries. Without annotations or context signals about alternatives, the agent has no explicit direction on 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Show system uptime' implies a read-only operation, but it doesn't specify output format, error conditions, permissions needed, or whether it runs a shell command (which could have security implications). For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, front-loaded with the core action ('Show system uptime'). There's no wasted language or redundancy, making it easy to parse quickly while conveying the essential purpose efficiently.
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 tool's low complexity (simple read operation, one optional parameter) and high schema coverage, the description is minimally complete. However, with no annotations and no output schema, it doesn't address behavioral aspects like output format or error handling. For a basic tool, this is adequate but leaves room for improvement in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting the 'args' parameter as 'Command arguments'. The description adds no parameter-specific information beyond this, but with zero required parameters and high schema coverage, the baseline is strong. Since the tool likely needs no parameters for basic uptime display, the description's simplicity is adequate, though it doesn't explain optional argument usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show system uptime' clearly states the tool's function with a specific verb ('show') and resource ('system uptime'), making the purpose understandable. However, it doesn't distinguish this tool from its siblings (like shell_date or shell_w which also show system information), missing differentiation that would warrant a higher score.
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 alternatives. With siblings like shell_w (which shows logged-in users and uptime) and shell_date (which shows current time), there's no indication of when shell_uptime is preferred or what unique value it offers, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but lacks details on behavioral traits such as error handling, output format, performance characteristics, or system dependencies. For a tool that queries system resources, this omission is significant and leaves the agent with incomplete operational understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality without unnecessary elaboration. Every word contributes directly to understanding the tool's purpose, making it appropriately sized and structured for quick comprehension.
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 the lack of annotations and output schema, the description is incomplete for a tool that interacts with system commands. It does not address potential complexities such as return formats, error conditions, or platform-specific behaviors. For a tool with no structured behavioral data, the description should provide more context to ensure reliable agent usage.
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 schema description coverage is 100%, with the parameter 'args' documented as 'Command arguments'. The description does not add meaning beyond this, as it does not explain what constitutes valid arguments or provide examples. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
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 specific verbs ('locate') and resources ('binary, source, and manual page files for a command'), distinguishing it from sibling tools that perform different operations like file viewing (shell_cat), system monitoring (shell_ps), or network queries (shell_dig). It precisely communicates what the tool does without being vague or tautological.
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 alternatives. It does not mention any prerequisites, exclusions, or specific contexts for usage, nor does it reference sibling tools that might serve similar purposes. This leaves the agent without explicit direction on appropriate application scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Show' implies a read-only operation, the description doesn't explicitly state safety aspects, permission requirements, or output format. It provides basic behavioral information but lacks details about what exactly gets returned or any constraints.
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, clear sentence with zero wasted words. It's perfectly front-loaded with the essential information and appropriately sized for this simple tool. Every word earns its place by directly communicating the tool's purpose.
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 (single basic operation), no annotations, no output schema, and 100% schema coverage, the description is reasonably complete. It clearly states what the tool does, though it could benefit from mentioning the output format (e.g., 'returns the absolute path as a string'). For such a straightforward tool, the description provides adequate context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting the 'args' parameter as 'Command arguments.' The description doesn't add parameter information beyond what the schema provides, but since this tool likely requires no arguments for its core function (showing the current directory), the minimal parameter documentation is adequate. The baseline would be 3 with full schema coverage, but the tool's simplicity and likely zero-argument usage justify a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show current working directory' clearly states the specific verb ('show') and resource ('current working directory'), making the tool's function immediately understandable. It distinguishes itself from sibling tools like shell_ls (list files) or shell_ps (show processes) by focusing exclusively on directory path display.
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 (when you need to know the current directory path) but doesn't explicitly state when to use this tool versus alternatives. No guidance is provided about when not to use it or about prerequisites, though the tool's simple purpose makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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:

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

Score Badge

Copy to your README.md:

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

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