AI-native developer tools via Model Context Protocol. A production-grade MCP server that gives AI agents (Claude, Cursor, Copilot, Continue, ...) safe, scoped access to your local development environment.
The MCP ecosystem is full of single-purpose tutorials and vendor-locked adapters. There is no well-maintained, multi-tool, framework-agnostic, production-quality MCP package for everyday developer tooling.
mcp-devtools fills that gap with 14 tools, 3 MCP Resources,
4 MCP Prompts, a Plugin API, two transport modes (stdio + HTTP
with auth), and an audit log — built on patterns refined in production
at DailyBot.
Related MCP server: Mac MCP
npx @oscarmarin/mcp-devtoolsAdd it to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"devtools": {
"command": "npx",
"args": ["-y", "@oscarmarin/mcp-devtools"]
}
}
}Or Cursor (~/.cursor/mcp.json): same block.
Create a mcp-devtools.json in your project root:
{
"transport": "http",
"port": 3333,
"auth": {
"token": "env:MCP_AUTH_TOKEN"
}
}Then start the server:
npx @oscarmarin/mcp-devtoolsThe MCP endpoint will be available at http://localhost:3333.
Group | Tools |
Filesystem |
|
Database |
|
Process |
|
OpenAPI |
|
Per-tool reference: docs/tools/.
The server exposes read-only data via MCP Resources:
URI | Description |
| Catalog of all registered tools with schemas |
| Server version, transport, scope, tool count |
Curated prompt templates for common development workflows:
Prompt | Description |
| Systematically debug an error using mcp-devtools tools |
| Review a file for bugs, security issues, and code quality |
| Explore and understand a project's structure and conventions |
| Refactor a function for readability, performance, or testability |
Extend mcp-devtools with custom tools — no fork required.
Config-based (load at startup):
{
"plugins": ["./my-tools.js", "@scope/mcp-plugin-foo"]
}Each plugin module default-exports an array of tool definitions:
import { defineTool } from "@oscarmarin/mcp-devtools";
import { z } from "zod";
export default [
defineTool({
name: "my_tool",
description: "Does something useful",
inputSchema: z.object({ input: z.string() }),
handler: async (args, config) => ({
ok: true,
data: { result: args.input.toUpperCase() },
}),
}),
];Configuration is loaded by cosmiconfig
from mcp-devtools.json, .mcp-devtoolsrc, or the mcpDevtools key in
package.json. See mcp-devtools.example.json
and docs/configuration.md for the full schema.
Zero-config is supported: running npx @oscarmarin/mcp-devtools with no config uses
schema defaults (RNF-05).
Four non-bypassable controls:
Filesystem scope boundary. Every path is resolved to an absolute and
compared against config.scope. Symlinks that escape scope throw
SCOPE_VIOLATION.
Command allowlist. run_command only executes binaries whose basename
is in allowedCommands. Invocation uses spawn(file, args) (no shell), so
shell-injection via the command argument is structurally impossible.
Database read-only mode. When readOnly: true, all SQL is parsed and
INSERT/UPDATE/DELETE/DROP/CREATE/GRANT are rejected. Queries run in
BEGIN READ ONLY ... ROLLBACK on PostgreSQL.
HTTP Bearer auth. When auth.token is configured, every HTTP request
must include Authorization: Bearer <token>. Comparison uses
crypto.timingSafeEqual to prevent timing attacks.
Additional safety measures:
Audit log. Opt-in NDJSON log of every tool invocation with timing, sanitized inputs, and result status.
Secret masking. get_env automatically masks values matching common
secret patterns (SECRET, TOKEN, PASSWORD, KEY, etc.).
OpenAPI host restriction. call_api only sends requests to hosts listed
in the spec's servers array.
Output capping. All tools cap their output to prevent context flooding (100KB for commands, 1MB for files, 200 rows for queries).
git clone https://github.com/marin1321/mcp-devtools.git
cd mcp-devtools
npm install
npm run dev # tsup --watch
npm run test # vitest
npm run typecheck # tsc --noEmit
npm run lint # eslint .See CONTRIBUTING.md for the full workflow and
CODE_OF_CONDUCT.md for community guidelines.
MIT © Oscar Humberto Marin Molina — oscarmarindev.com
Invoke an operation defined in an OpenAPI spec.
| Name | Required | Description | Default |
|---|---|---|---|
| specPath | Yes | ||
| operationId | Yes | ||
| pathParams | No | ||
| queryParams | No | ||
| body | No | ||
| headers | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits like side effects, authentication needs, error handling, or whether the operation is read-only or mutating. The agent is left blind.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is under-specified. It does not earn its place by providing essential context beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain return values, error conditions, or how the OpenAPI spec is used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no meaning for any of the 6 parameters (specPath, operationId, pathParams, queryParams, body, headers). The agent must infer entirely from names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it invokes an operation from an OpenAPI spec, which distinguishes it from sibling tools like parse_openapi that might parse specs. However, it could be more specific about what 'invoke' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives, such as direct API calls or other tools. No hints about prerequisites or common use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return column metadata for a table in a configured database connection.
| Name | Required | Description | Default |
|---|---|---|---|
| connection | No | default | |
| table | Yes | ||
| schema | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It implies a read-only operation but does not state idempotency, safety, or error handling for missing tables.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but overly minimal for a tool with three parameters and no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, low parameter coverage, and no annotations, the description lacks information on return format, error handling, and parameter usage, making it incomplete for accurate invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no parameter descriptions in the schema). The tool description adds no explanation for the three parameters (connection, table, schema), failing to clarify their meanings or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns column metadata for a table in a configured database connection, distinguishing it from siblings like list_tables (lists tables) and query_db (executes queries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, such as query_db or list_tables. No prerequisites or conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the provided message and a server-side ISO timestamp. Used to verify the MCP server pipeline end-to-end.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Arbitrary string the server will echo back |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the return values (message and timestamp) and implies a read-only, non-destructive operation. This is adequate for a simple echo tool, though it could explicitly state no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states what the tool does, second states its purpose. No extraneous information, perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is complete. It covers the return value and use case, with no missing information needed for selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the 'message' parameter as an arbitrary string. The description does not add additional parameter meaning, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the provided message and a server-side timestamp, and specifies it is used to verify the MCP server pipeline end-to-end. This distinguishes it from sibling tools like call_api or query_db, which perform different tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool (pipeline verification), implying a testing context. While it does not explicitly mention alternatives or when not to use, the dedicated test purpose is clear and sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return environment variables (process env or .env file) with optional masking.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | dotenv | |
| path | No | .env | |
| keys | No | ||
| maskSecrets | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries all burden but only mentions 'optional masking'. It does not disclose behaviors like error handling for missing files, default behavior when 'keys' is omitted, or how masking works (full vs partial).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise but lacks structure. It communicates the core function but does not organize information for quick scanning (e.g., no separation of purpose, usage, parameters). Could be improved with bullet points or a second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 0% schema coverage and no output schema, the description is incomplete. It omits return format, error conditions, and parameter dependencies, leaving significant gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description only adds meaning for 'maskSecrets' via the masking mention. The other three parameters ('source', 'path', 'keys') are left entirely unexplained, forcing reliance on parameter names and enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns environment variables from two specified sources (process env or .env file) with optional masking, distinguishing it from sibling tools that do not explicitly provide env variable access.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, nor on choosing between 'env' and 'dotenv' sources or when masking is appropriate. The usage context is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return metadata (size, type, MIME, line count, symlink info) for a file or directory.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool returns metadata and works for both files and directories, but omits details on side effects, authentication, error behavior, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, front-loaded with the key purpose and metadata types. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema or annotations, the description covers the input and output intent well. It lacks return value structure details (e.g., JSON format), but is sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It clarifies that the 'path' parameter refers to a file or directory, but does not specify path format (absolute/relative) or additional constraints beyond minLength.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns metadata (size, type, MIME, line count, symlink info) for a file or directory, using a specific verb and resource, and distinguishes it from siblings like read_file (content) and list_directory (list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidelines or alternatives are provided. The description implies the tool is for getting metadata, but does not clarify when to use it over siblings like read_file or list_directory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List directory entries inside the configured scope, with optional recursion and glob filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| depth | No | ||
| glob | No | ||
| includeHidden | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fails to disclose key behaviors like the scope definition, default recursion depth, handling of hidden files, or output format. It only mentions high-level features.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently conveys the core functionality without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters and no output schema, the description is far too brief; it omits critical details about output format, scope definition, parameter interactions, and error conditions, making it insufficient for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds only minimal context for depth and glob parameters, neglecting path, includeHidden, and detailed semantics like glob syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists directory entries with optional recursion and glob filtering, using a specific verb and resource. It is distinct from siblings like search_files and read_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided; the description does not indicate when to use this tool versus alternatives such as search_files or read_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List running processes, optionally filtered by name or listening port.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter processes by name substring (case-insensitive) | |
| port | No | Filter by TCP listening port | |
| limit | No | Maximum number of results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It states 'list running processes,' implying a read operation, but does not discuss system impact, required permissions, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words. It is front-loaded with the main action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three optional parameters and no output schema, the description is adequate but lacks details about the return format, pagination behavior (despite a limit parameter), or sorting. It covers the essential purpose but leaves practical usage details implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds 'optionally filtered by name or listening port,' which echoes the schema. No additional meaning is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (running processes), with optional filters. It distinguishes this tool from sibling tools like list_directory or list_tables by specifying 'processes' and the filtering options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 like run_command or read_logs. There is no mention of prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables in a configured database connection.
| Name | Required | Description | Default |
|---|---|---|---|
| connection | No | default | |
| schema | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'List tables'. It fails to disclose whether the operation is read-only, requires any permissions, or what the output format is. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks structure and essential details. It does not earn its place by providing value beyond the name; it is merely a restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two optional parameters and no output schema, the description should explain parameter behavior and return value. It fails to do so, leaving the agent with incomplete context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters with 0% description coverage. The description does not explain 'connection' or 'schema' (e.g., default behavior, acceptable values). It adds no meaning beyond the parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List tables') and the resource ('in a configured database connection'), distinguishing it from sibling tools like 'describe_table' and 'query_db'. However, it does not define what 'configured' means or clarify the scope of tables returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (e.g., 'describe_table' or 'query_db'). The description does not provide context for when listing tables is appropriate or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse an OpenAPI spec and return a summary of operations.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits like file access mode, error handling, or output format. Fails to compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Could be improved by front-loading key details within same length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description only says 'summary of operations' without specifying structure. Lacks file size limits, error conditions, or required permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter lacks description; schema coverage is 0%. Description adds no extra meaning about the 'path' parameter (e.g., local path, URL, supported extensions).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (Parse), resource (OpenAPI spec), and result (summary of operations). Unambiguous and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage context (when you have an OpenAPI spec file), but no explicit when-to-use or when-not-to-use guidance or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a parameterized SQL query against a configured database connection. Read-only by default.
| Name | Required | Description | Default |
|---|---|---|---|
| connection | No | default | |
| sql | Yes | ||
| params | No | ||
| timeoutMs | No | ||
| maxRows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states 'Read-only by default' but does not clarify if write queries are allowed or what the security implications are (e.g., authentication, effects on database state). This leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences with no redundancy, but it is somewhat terse given the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and no output schema, the description fails to cover essential context such as return format, error handling, connection configuration, or timeout behavior, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and no parameter-level information in the description, the agent receives no added meaning beyond the raw JSON schema. Parameters like connection, params, timeoutMs, and maxRows are unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Execute'), the resource ('parameterized SQL query'), and the context ('against a configured database connection'), distinguishing it from siblings like call_api or run_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as list_tables or describe_table. The read-only hint is present but does not specify exclusion for write queries or provide context-specific recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a text file inside the configured scope. Optionally restrict to a line range.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path from the configured scope root | |
| startLine | No | 1-based, inclusive. Returns from this line onwards. | |
| endLine | No | 1-based, inclusive. Returns up to and including this line. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only says 'Read a text file inside the configured scope,' omitting details like encoding, size limits, symlink handling, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded and to the point. Every word serves a purpose, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description should provide more context about return values, error handling, and file constraints. It is under-specified for a file-reading tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minor value by summarizing the line range as optional, but does not provide new semantics beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'text file', and specifies the scope restriction. It distinguishes from siblings like write_file and get_file_info by focusing on reading content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 does not mention when not to use it or suggest other tools for different scenarios, despite a list of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the tail of a configured log file with optional filter.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| tail | No | ||
| filter | No | ||
| jsonField | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions tail and filter but does not disclose read-only nature, error handling, symlink behavior, or whether output is raw text or formatted. Lacks behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is too brief for a 4-param tool with no annotations; it sacrifices completeness for brevity. Not sufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 parameters, no output schema, and no annotations. Description is extremely minimal, lacking return format, default behavior, constraints, and error conditions. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, description should compensate. It only mentions 'filter' and implies 'tail' via description, but omits the required 'path' and 'jsonField' parameter entirely. Adds minimal value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads a log file tail with optional filter, but does not distinguish from sibling tool 'read_file' which could read any file including logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool instead of alternatives like read_file or run_command, nor any prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spawn a process from the configured allowedCommands list. Captures stdout/stderr with caps and a timeout.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Binary name (must be in allowedCommands) | |
| args | No | ||
| cwd | No | ||
| timeoutMs | No | ||
| env | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose side effects, but it only mentions capturing output with caps and a timeout. It does not explain behavior on timeout (e.g., process killed), error handling, or security implications beyond the allowed list. This leaves significant gaps for a process spawning tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action: 'Spawn a process from the configured allowedCommands list.' No redundant information, every word is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, nested objects), lack of output schema, and no annotations, the description is severely incomplete. It does not explain caps limits, timeout behavior, or how to configure environment variables. An agent cannot safely invoke this tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the 'command' parameter has a brief description. Schema coverage is 20%, and the description adds no extra meaning for 'args', 'cwd', 'timeoutMs', or 'env'. The schema defines types and constraints, but the description does not clarify default values, env overriding, or how args are passed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it spawns a process from an allowed commands list, capturing stdout/stderr. The verb 'spawn' and resource 'process from allowedCommands list' are specific and distinguish from siblings like 'list_processes' or 'write_file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is limited to a configured list but does not explicitly say when to use it versus alternatives like 'call_api' or when not to use it. No guidance on prerequisites like verifying the allowed commands list or handling disallowed commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for a pattern (literal or regex) across files inside the configured scope.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | ||
| path | No | . | |
| glob | No | ||
| regex | No | Treat `pattern` as a regular expression | |
| caseInsensitive | No | ||
| contextLines | No | ||
| maxResults | No | ||
| includeHidden | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions searching across files but does not disclose key behaviors like the default case-insensitivity (caseInsensitive defaults false), exclusion of hidden files (includeHidden defaults false), or the maximum file size or scope limitations. The agent is left unaware of critical 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It avoids redundancy, but could benefit from a bit more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description is insufficient. It does not explain the return format, behavior of parameters, or edge cases (e.g., no matches), leaving the agent with incomplete information to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, yet the description only mentions 'pattern' and the choice of literal or regex. It does not explain 'path', 'glob', 'caseInsensitive', 'contextLines', 'maxResults', or 'includeHidden', leaving the agent to infer their meanings from names alone, which may be ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching for a pattern (literal or regex) across files. However, 'inside the configured scope' is vague and does not differentiate well from sibling tools like 'list_directory' or 'read_file', which also involve file access.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 such as 'read_file' or 'list_directory'. The description lacks any context about preferred scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a file atomically inside the configured scope (writes to a temp file then renames).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| encoding | No | utf-8 | |
| createDirs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses atomic write behavior and the temp file rename mechanism, which are critical for safe use. However, it omits details like overwrite behavior, permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. It front-loads the core purpose ('Write a file atomically') and adds a parenthetical detail. Every part is informative with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description is incomplete. It does not explain parameters, return value, or error conditions. The atomicity info is valuable but insufficient for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain any parameters. It does not clarify that path is required, content is data to write, or the meaning of encoding and createDirs. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a file atomically within a configured scope, using a temp file then rename. It distinguishes from siblings like read_file by specifying write and atomicity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for writing files atomically, but does not explicitly provide when-to-use vs alternatives or exclusions. The atomicity note offers some guidance for concurrent safe writes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation: database metadata vs query, file read vs write vs listing vs search, process listing vs command execution, API calling vs spec parsing, etc. No two tools have overlapping purposes.
All tools follow a verb_noun pattern in snake_case (e.g., list_directory, read_file, query_db). The verbs vary but are appropriate for the action, and the naming is uniform throughout.
15 tools is slightly broad for a devtools server covering databases, files, processes, APIs, logs, and environment variables, but each tool has a clear role and the count is not excessive for a general-purpose utility server.
Core developer utilities are covered (file ops, database queries, command execution, API handling), but there are gaps like no process kill, no file editing, no HTTP utilities, and database is read-only. The set feels like a curated collection rather than a comprehensive toolkit.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Hosted MCP server for live public-data APIs and Skills for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/marin1321/mcp-devtools'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
