Skip to main content
Glama
agileandy

MCP Secure Local Server

by agileandy
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MCP Secure Local Server

A production-ready, security-first Model Context Protocol (MCP) server that runs locally with strict security controls while allowing controlled external network access for specific use cases like web search.

Features

  • Security-First Design: All operations are validated against a configurable security policy

  • Network Firewall: Block all external network access except explicitly allowlisted endpoints

  • Input Validation: JSON Schema validation, path traversal protection, command sanitization

  • Rate Limiting: Per-tool rate limits to prevent abuse

  • Audit Logging: JSON Lines format logging with sensitive data redaction

  • Plugin System: Extensible architecture for adding new tools

  • MCP Protocol Compliant: Full JSON-RPC 2.0 over STDIO transport

Related MCP server: MCP Toolkit

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd mcp-server

# Install dependencies with uv
uv sync

Running the Server

# Run with default policy
uv run python main.py

# Run with custom policy file
uv run python main.py --policy /path/to/policy.yaml

# Show version
uv run python main.py --version

Integration with MCP Clients

This server works with any MCP-compatible client. Add the following to your client's MCP configuration:

{
  "mcpServers": {
    "secure-local": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp-server/main.py"],
      "env": {}
    }
  }
}

Example client configuration locations:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

  • Other MCP clients: Refer to your client's documentation for the configuration file location

Architecture

mcp-server/
├── main.py                    # CLI entry point
├── config/
│   └── policy.yaml            # Security policy configuration
├── src/
│   ├── server.py              # Main MCP server
│   ├── protocol/
│   │   ├── jsonrpc.py         # JSON-RPC 2.0 parsing
│   │   ├── transport.py       # STDIO transport
│   │   ├── lifecycle.py       # MCP lifecycle management
│   │   └── tools.py           # tools/list & tools/call handlers
│   ├── plugins/
│   │   ├── base.py            # Plugin base class
│   │   ├── loader.py          # Plugin discovery
│   │   ├── dispatcher.py      # Tool call routing
│   │   ├── discovery.py       # Built-in: Progressive disclosure tools
│   │   ├── websearch.py       # Example: DuckDuckGo search plugin
│   │   └── bugtracker.py      # Example: Bug tracking plugin
│   └── security/
│       ├── policy.py          # Policy loader
│       ├── firewall.py        # Network access control
│       ├── validator.py       # Input validation
│       ├── engine.py          # Integrated security engine
│       └── audit.py           # Audit logging
└── tests/                     # Test suite (343 tests, 96%+ coverage)

Security Policy

The security policy is defined in YAML format. See config/policy.yaml for a complete example.

Network Security

network:
  # Allowed local network ranges
  allowed_ranges:
    - "127.0.0.0/8"
    - "10.0.0.0/8"
    - "192.168.0.0/16"
  
  # Explicitly allowed external endpoints
  allowed_endpoints:
    - host: "lite.duckduckgo.com"
      ports: [443]
      description: "DuckDuckGo search"
  
  # Blocked ports (even on local network)
  blocked_ports:
    - 22  # SSH  
  
  # DNS settings
  allow_dns: true
  dns_allowlist:
    - "lite.duckduckgo.com"

Filesystem Security

filesystem:
  # Allowed paths (supports globs and env vars)
  allowed_paths:
    - "${HOME}/projects/**"
    - "/tmp/mcp-workspace/**"
  
  # Denied paths (takes precedence)
  denied_paths:
    - "**/.ssh/**"
    - "**/.aws/**"
    - "**/*.pem"
    - "**/.env"

Tool Configuration

tools:
  # Rate limits (requests per minute)
  rate_limits:
    default: 60
    web_search: 20
  
  # Execution timeout
  timeout: 30

Audit Logging

audit:
  log_file: "${HOME}/.mcp-secure/audit.log"
  log_level: "INFO"

Built-in Tools

The server automatically registers discovery tools for progressive disclosure, enabling agents to efficiently find and load only the tools they need.

search_tools

Search for available tools by keyword or category. Use detail_level to control context usage.

Input Schema:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Keyword to search in tool names and descriptions"
    },
    "category": {
      "type": "string",
      "description": "Filter by plugin category (e.g., 'bugtracker')"
    },
    "detail_level": {
      "type": "string",
      "enum": ["name", "summary", "full"],
      "description": "Level of detail: 'name' (just names), 'summary' (names + descriptions), 'full' (complete schemas)"
    }
  }
}

Example - Find bug-related tools with minimal context:

{
  "name": "search_tools",
  "arguments": {
    "query": "bug",
    "detail_level": "name"
  }
}
// Returns: ["add_bug", "get_bug", "update_bug", "close_bug", "list_bugs", "search_bugs_global"]

Example - Get full schema for a specific category:

{
  "name": "search_tools",
  "arguments": {
    "category": "websearch",
    "detail_level": "full"
  }
}

list_categories

List all available tool categories (plugins) with tool counts. Use this to discover capabilities before searching.

Input Schema:

{
  "type": "object",
  "properties": {}
}

Example Response:

[
  {
    "category": "discovery",
    "version": "1.0.0",
    "tool_count": 2,
    "tools": ["search_tools", "list_categories"]
  },
  {
    "category": "websearch",
    "version": "1.0.0",
    "tool_count": 1,
    "tools": ["web_search"]
  },
  {
    "category": "bugtracker",
    "version": "1.0.0",
    "tool_count": 7,
    "tools": ["init_bugtracker", "add_bug", "get_bug", "update_bug", "close_bug", "list_bugs", "search_bugs_global"]
  }
]

Example Plugins

The server includes example plugins to demonstrate the plugin architecture. These are provided as reference implementations showing how to build your own plugins for any use case.

web_search (Example Plugin)

An example plugin that searches the web using DuckDuckGo. Demonstrates how to build plugins that make external network requests within the security policy.

Input Schema:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query"
    },
    "max_results": {
      "type": "integer",
      "description": "Maximum results to return (default: 5)"
    }
  },
  "required": ["query"]
}

Example:

{
  "name": "web_search",
  "arguments": {
    "query": "Python asyncio tutorial",
    "max_results": 3
  }
}

Bug Tracker (Example Plugin)

An example plugin implementing a local bug tracking system with a centralized SQLite database. Demonstrates how to build plugins that manage local state, support multiple projects, and perform complex queries.

init_bugtracker

Initialize bug tracking for a project.

Input Schema:

{
  "type": "object",
  "properties": {
    "project_path": {
      "type": "string",
      "description": "Path to project directory (defaults to cwd)"
    }
  }
}

add_bug

Add a new bug to the tracker.

Input Schema:

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Brief title for the bug"
    },
    "description": {
      "type": "string",
      "description": "Detailed description"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"],
      "description": "Bug priority (default: medium)"
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Tags for categorization"
    },
    "project_path": {
      "type": "string",
      "description": "Path to project directory (defaults to cwd)"
    }
  },
  "required": ["title"]
}

get_bug

Retrieve a bug by ID.

Input Schema:

{
  "type": "object",
  "properties": {
    "bug_id": {
      "type": "string",
      "description": "The bug ID to retrieve"
    },
    "project_path": {
      "type": "string",
      "description": "Path to project directory (defaults to cwd)"
    }
  },
  "required": ["bug_id"]
}

update_bug

Update an existing bug's status, priority, tags, or related bugs. Supports note-only updates for progress tracking.

Input Schema:

{
  "type": "object",
  "properties": {
    "bug_id": {
      "type": "string",
      "description": "The bug ID to update"
    },
    "status": {
      "type": "string",
      "enum": ["open", "in_progress", "closed"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "New tags (replaces existing)"
    },
    "related_bugs": {
      "type": "array",
      "description": "Related bugs with relationship type"
    },
    "note": {
      "type": "string",
      "description": "Note for the history entry"
    },
    "project_path": {
      "type": "string"
    }
  },
  "required": ["bug_id"]
}

close_bug

Close a bug with a resolution note.

Input Schema:

{
  "type": "object",
  "properties": {
    "bug_id": {
      "type": "string",
      "description": "The bug ID to close"
    },
    "resolution": {
      "type": "string",
      "description": "Resolution note explaining how the bug was fixed"
    },
    "project_path": {
      "type": "string"
    }
  },
  "required": ["bug_id"]
}

list_bugs

List bugs with optional filtering.

Input Schema:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["open", "in_progress", "closed"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Filter by tags (must have ALL specified tags)"
    },
    "project_path": {
      "type": "string"
    }
  }
}

search_bugs_global

Search bugs across all indexed projects.

Input Schema:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["open", "in_progress", "closed"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

Example - Create and track a bug:

// Add a bug
{
  "name": "add_bug",
  "arguments": {
    "title": "Login button not responding",
    "description": "The login button on the home page doesn't trigger the auth flow",
    "priority": "high",
    "tags": ["ui", "auth"]
  }
}

// Update with progress
{
  "name": "update_bug",
  "arguments": {
    "bug_id": "BUG-001",
    "status": "in_progress",
    "note": "Identified missing onClick handler"
  }
}

// Close with resolution
{
  "name": "close_bug",
  "arguments": {
    "bug_id": "BUG-001",
    "resolution": "Added onClick handler to LoginButton component"
  }
}

Creating Custom Plugins

Python Plugins

Plugins must inherit from PluginBase and implement the required methods:

from src.plugins.base import PluginBase, ToolDefinition, ToolResult

class MyPlugin(PluginBase):
    @property
    def name(self) -> str:
        return "my_plugin"
    
    @property
    def version(self) -> str:
        return "1.0.0"
    
    def get_tools(self) -> list[ToolDefinition]:
        return [
            ToolDefinition(
                name="my_tool",
                description="Does something useful",
                input_schema={
                    "type": "object",
                    "properties": {
                        "input": {"type": "string"}
                    },
                    "required": ["input"]
                },
            )
        ]
    
    def execute(self, tool_name: str, arguments: dict) -> ToolResult:
        if tool_name == "my_tool":
            result = do_something(arguments["input"])
            return ToolResult(
                content=[{"type": "text", "text": result}]
            )
        return ToolResult(
            content=[{"type": "text", "text": "Unknown tool"}],
            is_error=True
        )

Register the plugin in main.py:

from my_plugin import MyPlugin

server.register_plugin(MyPlugin())

External Plugins (Non-Python)

The plugin system can support tools written in any language (Rust, JavaScript, TypeScript, Go, etc.) through a subprocess wrapper approach. This is a planned feature - contributions welcome.

Architecture Overview

External plugins run as separate processes, communicating with the Python wrapper via JSON over stdin/stdout:

┌─────────────────────────────────────────────────────────────┐
│                     MCP Server (Python)                      │
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │ WebSearch    │    │ BugTracker   │    │ External     │   │
│  │ (Python)     │    │ (Python)     │    │ Plugin       │   │
│  └──────────────┘    └──────────────┘    │ (Wrapper)    │   │
│                                          └──────┬───────┘   │
│                                                 │            │
└─────────────────────────────────────────────────┼────────────┘
                                                  │ JSON/stdin/stdout
                                                  ▼
                                          ┌──────────────┐
                                          │ my-rust-tool │
                                          │ (subprocess) │
                                          └──────────────┘

How It Works

  1. Python Wrapper: A thin ExternalPlugin class inherits from PluginBase and handles the subprocess lifecycle

  2. Manifest: A manifest.yaml declares the tool definitions and points to the executable

  3. Contract: The external tool receives JSON on stdin and writes JSON to stdout

Manifest Format

name: my-rust-tools
version: "1.0.0"
type: external
executable: ./target/release/my-rust-tool

tools:
  - name: calculate_hash
    description: Calculate cryptographic hash of input
    input_schema:
      type: object
      properties:
        algorithm:
          type: string
          enum: [sha256, sha512, blake3]
        input:
          type: string
      required: [algorithm, input]

External Tool Contract

The external executable must:

  1. Accept a JSON object on stdin:

{
  "tool": "calculate_hash",
  "arguments": {
    "algorithm": "sha256",
    "input": "hello world"
  }
}

  1. Return a JSON object on stdout:

{
  "content": [
    {"type": "text", "text": "sha256: b94d27b9934d3e08..."}
  ],
  "isError": false
}

  1. Exit with code 0 on success, non-zero on failure

Example: Rust Tool

use serde::{Deserialize, Serialize};
use std::io::{self, BufRead, Write};

#[derive(Deserialize)]
struct Request {
    tool: String,
    arguments: serde_json::Value,
}

#[derive(Serialize)]
struct Response {
    content: Vec<Content>,
    #[serde(rename = "isError")]
    is_error: bool,
}

#[derive(Serialize)]
struct Content {
    #[serde(rename = "type")]
    content_type: String,
    text: String,
}

fn main() {
    let stdin = io::stdin();
    let line = stdin.lock().lines().next().unwrap().unwrap();
    let request: Request = serde_json::from_str(&line).unwrap();
    
    let result = match request.tool.as_str() {
        "calculate_hash" => calculate_hash(request.arguments),
        _ => Err(format!("Unknown tool: {}", request.tool)),
    };
    
    let response = match result {
        Ok(text) => Response {
            content: vec![Content { content_type: "text".into(), text }],
            is_error: false,
        },
        Err(e) => Response {
            content: vec![Content { content_type: "text".into(), text: e }],
            is_error: true,
        },
    };
    
    println!("{}", serde_json::to_string(&response).unwrap());
}

Example: Node.js Tool

const readline = require('readline');

const rl = readline.createInterface({ input: process.stdin });

rl.on('line', (line) => {
  const request = JSON.parse(line);
  
  let response;
  try {
    const result = handleTool(request.tool, request.arguments);
    response = {
      content: [{ type: 'text', text: result }],
      isError: false
    };
  } catch (e) {
    response = {
      content: [{ type: 'text', text: e.message }],
      isError: true
    };
  }
  
  console.log(JSON.stringify(response));
  process.exit(0);
});

function handleTool(tool, args) {
  switch (tool) {
    case 'format_json':
      return JSON.stringify(JSON.parse(args.input), null, 2);
    default:
      throw new Error(`Unknown tool: ${tool}`);
  }
}

Security Considerations for External Plugins

  1. Process Isolation: External tools run in separate processes with their own memory space

  2. Timeout Enforcement: The wrapper kills subprocesses that exceed the configured timeout

  3. No Network Inheritance: Subprocess network access is governed by OS-level controls

  4. Executable Allowlist: Only executables listed in registered manifests can be invoked

  5. Input Validation: JSON schemas are validated before passing to the subprocess

Trade-offs

Aspect

Python Plugin

External Plugin

Startup latency

None

~10-50ms per call

Memory

Shared with server

Separate process

Language

Python only

Any language

Debugging

Easy

Harder (separate process)

Security

Shared memory space

Process isolation

When to Use External Plugins

  • Performance-critical tools: Rust/Go for CPU-intensive operations

  • Existing CLI tools: Wrap existing binaries without rewriting

  • Language-specific libraries: Use npm packages, Cargo crates, etc.

  • Team expertise: Let teams use their preferred language

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_server.py -v

Linting

# Check for issues
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Format code
uv run ruff format .

Project Structure

Directory

Purpose

src/protocol/

MCP protocol implementation (JSON-RPC, STDIO, lifecycle)

src/plugins/

Plugin system and built-in plugins

src/security/

Security layer (firewall, validation, audit)

tests/

Test suite

config/

Configuration files

MCP Protocol Support

This server implements MCP protocol version 2025-11-25 with support for:

Method

Description

initialize

Initialize the connection

notifications/initialized

Confirm initialization complete

tools/list

List available tools

tools/call

Execute a tool

Security Considerations

  1. Network Isolation: By default, all external network access is blocked. Only explicitly allowlisted endpoints can be reached.

  2. Path Traversal Protection: All file paths are validated against allowed/denied patterns to prevent accessing sensitive files.

  3. Command Injection Prevention: Commands are sanitized to block dangerous patterns like shell operators.

  4. Rate Limiting: Per-tool rate limits prevent abuse and resource exhaustion.

  5. Audit Trail: All operations are logged with timestamps, request IDs, and sanitized arguments.

License

MIT License - see LICENSE file for details.

Available Tools

15 tools
add_bugC

Add a new bug to the tracker.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesBrief title for the bug.
descriptionNoDetailed description of the bug.
priorityNoBug priority (default: medium).
tagsNoTags for categorizing the bug.
project_pathNoPath to project directory (defaults to cwd).

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states the action without disclosing behavioral traits. It does not mention permissions needed, whether the bug is saved immediately, if there are rate limits, or what happens on success/failure, leaving critical operational details unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with zero wasted words, making it highly efficient and front-loaded. It immediately conveys the core purpose 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?

For a mutation tool with no annotations and no output schema, the description is inadequate. It lacks details on behavioral aspects like error handling, response format, or system state changes, leaving gaps that could hinder an AI agent's ability 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?

Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no additional meaning beyond the schema, such as explaining interactions between parameters or usage examples, but this is acceptable given the high schema coverage, resulting in a baseline score.

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 action ('Add') and resource ('a new bug to the tracker'), making the purpose immediately understandable. However, it does not differentiate this tool from sibling tools like 'update_bug' or 'close_bug' beyond the basic verb, missing explicit distinction in scope or intent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'update_bug' or 'close_bug', nor does it mention prerequisites like needing an initialized tracker. The description only states the basic action without context for selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

close_bugA

Close a bug (convenience wrapper for update_bug with status=closed).

ParametersJSON Schema
NameRequiredDescriptionDefault
bug_idYesThe bug ID to close.
resolutionNoResolution note explaining how the bug was fixed.
project_pathNoPath to project directory (defaults to cwd).

TDQS

A4.2/5.0
Behavior3/5

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 that this is a mutation operation (closing a bug) and that it wraps another tool, but doesn't mention permissions needed, whether the operation is reversible, error conditions, or what happens to the bug after closing. For a mutation tool with zero annotation coverage, this is adequate but leaves important behavioral details unspecified.

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 conveys the essential information: what the tool does and its relationship to another tool. Every word earns its place with zero wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description does well by explaining it's a wrapper for update_bug, which provides important context. However, it doesn't mention what the tool returns or error handling. Given the complexity (simple wrapper) and good sibling tool context, it's mostly complete but could benefit from return value 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?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description doesn't add any parameter-specific information beyond what's in the schema. According to the rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('close a bug') and resource ('bug'), and explicitly distinguishes it from its sibling 'update_bug' by noting it's a convenience wrapper for that tool with status=closed. This provides clear differentiation from alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('close a bug') versus alternatives by naming the alternative ('update_bug') and specifying the condition under which this wrapper should be used (when you want to set status=closed). This provides perfect guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

configure_figma_storiesC

Configure Figma Stories plugin with API tokens and AI settings. Set FIGMA_API_TOKEN environment variable for Figma access.

ParametersJSON Schema
NameRequiredDescriptionDefault
figma_tokenNoFigma API token (alternative: set FIGMA_API_TOKEN env var)
ai_enabledNoEnable AI enhancement for story generation
ai_endpointNoAI API endpoint URLhttps://openrouter.ai/api/v1
ai_modelNoAI model namenvidia/nemotron-3-nano-30b-a3b:free
ai_api_keyNoAI API key (alternative: set AI_API_KEY env var)

TDQS

C2.9/5.0
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. It mentions configuration actions but doesn't specify whether this creates persistent settings, requires specific permissions, has side effects, or what happens on success/failure. The phrase 'Configure' implies mutation but lacks details about scope and impact.

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 efficiently structured in two sentences that directly address the tool's purpose and a key implementation detail. No wasted words, though it could be slightly more front-loaded with the core purpose.

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 configuration tool with 5 parameters and no annotations or output schema, the description is insufficient. It doesn't explain what 'configuration' entails (persistent storage? session-only?), success indicators, error conditions, or relationship to other tools. The absence of output schema increases the need for behavioral context that's 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?

Schema description coverage is 100%, providing complete parameter documentation. The description adds minimal value beyond the schema, mentioning environment variable alternatives for two parameters but not explaining configuration persistence, validation, or interaction between parameters. Baseline 3 is appropriate given the comprehensive schema coverage.

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 action ('Configure') and target ('Figma Stories plugin') with specific configuration areas ('API tokens and AI settings'), making the purpose evident. It doesn't explicitly differentiate from sibling tools like 'init_bugtracker' or 'get_config_status', but the specificity of 'Figma Stories plugin' provides reasonable 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 like 'init_bugtracker' or 'get_config_status'. It mentions setting environment variables as alternatives for some parameters, but offers no context about prerequisites, timing, or tool selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_user_storiesC

Generate agile user stories from a Figma design file. Creates markdown file with stories, epics, and acceptance criteria.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_urlYesFigma file URL (e.g., https://www.figma.com/file/abc123/...)
pagesNoSpecific pages to process (empty = all pages)
output_fileNoOutput filename (default: {design_title}_user_stories.md)
interactiveNoPrompt for overwrite/append if file exists

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions creating a markdown file but doesn't disclose critical traits like whether it overwrites existing files by default, requires authentication for Figma access, handles errors, or has rate limits. The 'interactive' parameter hints at some behavior, but overall disclosure is inadequate for a tool with mutation potential.

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 highly concise and front-loaded: two sentences that directly state the tool's function and output. Every word earns its place with no redundancy or fluff, making it easy for an agent to quickly grasp the core purpose.

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 (generating user stories from design files) and lack of annotations and output schema, the description is insufficient. It doesn't explain what the markdown file contains beyond 'stories, epics, and acceptance criteria', nor does it cover error handling, authentication needs, or file system interactions. For a tool with potential side effects, 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?

Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't explain the format of the markdown output or how 'pages' interact with the Figma file). Baseline 3 is appropriate as the schema handles parameter semantics effectively.

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: 'Generate agile user stories from a Figma design file' specifies the action (generate) and resource (user stories from Figma). It distinguishes from siblings like 'preview_user_stories' by emphasizing creation of a markdown file, though it doesn't explicitly contrast with 'configure_figma_stories'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention when to choose 'generate_user_stories' over 'preview_user_stories' or 'configure_figma_stories', nor does it specify prerequisites like needing a valid Figma file URL. The description implies usage for creating stories but lacks explicit context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bugC

Get a bug by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
bug_idYesThe bug ID to retrieve.
project_pathNoPath to project directory (defaults to cwd).

TDQS

C2.7/5.0
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 'Get a bug by ID', which implies a read-only operation, but doesn't cover aspects like error handling (e.g., what happens if the bug ID doesn't exist), authentication needs, rate limits, or return format. This leaves significant gaps 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 extremely concise with a single sentence 'Get a bug by ID.', which is front-loaded and wastes no words. It efficiently conveys the core purpose without unnecessary elaboration, 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 no annotations and no output schema, the description is incomplete for a tool with 2 parameters and sibling tools. It lacks details on behavioral traits, return values, and usage context. For a read operation in a bug-tracking system, more information on error cases or output structure would be beneficial to ensure correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema fully documents both parameters (bug_id and project_path). The description adds no additional meaning beyond what's in the schema, such as examples or constraints. 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.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get a bug by ID' clearly states the action (get) and resource (bug), but it's vague about scope and doesn't distinguish from siblings like 'list_bugs' or 'search_bugs_global'. It specifies retrieval by ID, which is somewhat specific but lacks detail about what constitutes a 'bug' 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?

No guidance is provided on when to use this tool versus alternatives such as 'list_bugs' or 'search_bugs_global'. The description implies usage for retrieving a specific bug by ID, but it doesn't mention prerequisites, exclusions, or contextual factors like needing a project directory.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_config_statusB

Get current configuration status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
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 'Get' which implies a read operation, but doesn't specify if it's safe, requires permissions, has side effects, or details the return format (e.g., JSON structure, error handling). This leaves significant gaps for an agent to understand how to use it effectively.

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 is front-loaded and efficiently conveys the core action, making it easy to parse and understand 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 lack of annotations and output schema, the description is incomplete. It doesn't explain what 'configuration status' entails (e.g., settings, health, version), how the result is structured, or potential errors. For a tool with no structured context, this leaves the agent guessing about the output and usage nuances.

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 0 parameters with 100% coverage, so no parameter information is needed. The description doesn't add parameter details, which is appropriate here, but it could have mentioned if any implicit parameters (like context or defaults) are involved, though not required for a high score given the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'current configuration status', making the purpose understandable. However, it doesn't differentiate from sibling tools like 'configure_figma_stories' or 'init_bugtracker' which might also relate to configuration, leaving room for ambiguity.

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, context, or exclusions, such as whether it should be used before or after configuration changes, or if it's for debugging or monitoring purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

init_bugtrackerC

Initialize bug tracker for a project. Creates .bugtracker/ directory.

ParametersJSON Schema
NameRequiredDescriptionDefault
project_pathNoPath to project directory (defaults to cwd).

TDQS

C2.9/5.0
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. It states the tool creates a directory, implying a write operation, but doesn't disclose behavioral traits such as permissions needed, whether it overwrites existing directories, error handling, or side effects. This is a significant gap for a mutation tool with zero 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 sentence that front-loads the purpose and outcome with zero waste. Every word earns its place, 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 as a mutation operation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects like success/failure responses, prerequisites, or integration with sibling tools, which are crucial for an agent to use it correctly in context.

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 already documents the single parameter 'project_path' with its type and default. The description doesn't add any parameter-specific information beyond what the schema provides, such as format examples or constraints, meeting the baseline for high schema coverage.

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 action ('Initialize bug tracker') and the resource ('for a project'), with the specific outcome of creating a .bugtracker/ directory. It distinguishes from siblings like 'add_bug' or 'configure_figma_stories' by focusing on setup rather than bug management or configuration, though it doesn't explicitly contrast with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., whether the project must exist), exclusions, or related tools like 'configure_figma_stories' for similar setup tasks, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_bugsC

List bugs with optional filtering by status, priority, and tags.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNoFilter by status.
priorityNoFilter by priority.
tagsNoFilter by tags (must have ALL specified tags).
project_pathNoPath to project directory (defaults to cwd).

TDQS

C2.9/5.0
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. It states this is a list operation with filtering but doesn't disclose behavioral traits like pagination, rate limits, authentication needs, or what happens if no filters are applied (e.g., returns all bugs). For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.

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 action ('List bugs') and briefly mentions key filtering options. There is zero waste or redundancy, making it easy to parse quickly. It's appropriately sized for a straightforward list tool.

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 and no output schema, the description is incomplete for a tool with 4 parameters and sibling alternatives. It doesn't explain return values, error conditions, or behavioral context like default behaviors (e.g., what 'cwd' means for project_path). For a list tool with filtering complexity, more completeness 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?

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds minimal value by mentioning filtering by status, priority, and tags, but doesn't provide additional semantics beyond what's in the schema (e.g., how tags filtering works is only in schema). With high schema coverage, baseline 3 is appropriate as the description doesn't significantly enhance parameter understanding.

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 verb ('List') and resource ('bugs'), making the purpose immediately understandable. It distinguishes from sibling tools like 'get_bug' (singular) and 'search_bugs_global' (broader search), though it doesn't explicitly mention these alternatives. The description is specific but could be more precise about scope compared to siblings.

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 mentions optional filtering but provides no guidance on when to use this tool versus alternatives like 'search_bugs_global' or 'get_bug'. It doesn't specify prerequisites (e.g., needing an initialized bugtracker) or context for filtering. Usage is implied through parameter mentions but lacks explicit when/when-not instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_categoriesA

List all available tool categories (plugins) with their tool counts. Use this to discover what capabilities are available before searching.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions that the tool lists categories 'with their tool counts', which adds useful behavioral context about the output format. However, it doesn't disclose other traits like rate limits, error conditions, or whether the data is cached/live, leaving some gaps in behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero waste: the first states the purpose, and the second provides usage guidance. It is front-loaded with the core functionality and appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is reasonably complete. It explains what the tool does and when to use it. However, without an output schema, it could benefit from more detail on the return format (e.g., structure of categories and counts), though the mention of 'tool counts' partially addresses this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description doesn't add parameter semantics (since there are none), but this is appropriate. A baseline of 4 is applied for zero-parameter tools when the schema fully covers them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'all available tool categories (plugins) with their tool counts', making the purpose specific and actionable. It distinguishes this from sibling tools like 'list_bugs' or 'list_figma_pages' by focusing on categories rather than specific data types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'Use this to discover what capabilities are available before searching.' This provides clear context for usage, distinguishing it from other list tools by positioning it as a discovery mechanism rather than a data retrieval operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_figma_pagesC

List pages in a Figma file for selection.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_urlYesFigma file URL

TDQS

C2.9/5.0
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. It states the tool lists pages but doesn't disclose behavioral traits such as whether it's read-only, requires authentication, has rate limits, returns paginated results, or what format the output takes. 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 sentence that directly states the tool's purpose without waste. It's appropriately sized and front-loaded, making it easy to understand 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 no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, output format, error handling, or integration with sibling tools like 'configure_figma_stories'. For a tool with minimal structured data, this description doesn't provide enough context for 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 'file_url' parameter documented as 'Figma file URL'. The description doesn't add any meaning beyond this, such as URL format examples or validation rules, so it meets the baseline of 3 where the schema does 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 clearly states the action ('List pages') and resource ('in a Figma file'), with the purpose 'for selection' adding context. However, it doesn't differentiate from potential siblings like 'get_figma_pages' or 'browse_figma_pages' since none exist in the provided sibling list, so it's not a full 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description mentions 'for selection' but doesn't specify prerequisites, exclusions, or related tools like 'configure_figma_stories' from the sibling list, leaving usage context implied at best.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_user_storiesA

Preview generated user stories without writing to file. Shows first 3 stories per epic.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_urlYesFigma file URL
pagesNoSpecific pages to preview

TDQS

A3.5/5.0
Behavior3/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 adds value by specifying 'without writing to file' (indicating a read-only preview) and 'Shows first 3 stories per epic' (limiting output), but it doesn't cover aspects like error handling, authentication needs, or rate limits. The description doesn't contradict annotations, but it lacks comprehensive behavioral context 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 highly concise and front-loaded: the first sentence states the core purpose, and the second adds critical scope information. Every sentence earns its place by providing essential details without redundancy, 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.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but has gaps. It covers the action and output limitation, but without annotations or an output schema, it doesn't explain return values, error cases, or integration with sibling tools. This makes it minimally viable but incomplete for full contextual 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 input schema already documents both parameters ('file_url' and 'pages') fully. The description doesn't add any parameter-specific details beyond what the schema provides, such as explaining how 'pages' interact with 'file_url' or format examples. 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: 'Preview generated user stories without writing to file' specifies the action (preview) and resource (user stories), with the additional detail 'Shows first 3 stories per epic' providing scope. However, it doesn't explicitly differentiate from sibling tools like 'generate_user_stories' or 'configure_figma_stories', which could be related alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating 'without writing to file', suggesting this is for review before committing changes, but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'generate_user_stories' or 'list_figma_pages'. No exclusions or prerequisites are mentioned, leaving some ambiguity in context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_bugs_globalC

Search bugs across all indexed projects.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNoFilter by status.
priorityNoFilter by priority.
tagsNoFilter by tags (must have ALL specified tags).

TDQS

C2.9/5.0
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. It states the search scope but doesn't mention important behavioral aspects like pagination, rate limits, authentication requirements, result format, or whether this is a read-only operation. The description is insufficient for a search tool with zero 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 sentence that communicates the core purpose without any wasted words. It's appropriately sized for a search tool and gets straight to the point.

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 search tool with no annotations and no output schema, the description is inadequate. It doesn't explain what the search returns, how results are structured, whether there are limitations on search scope, or any performance characteristics. The description should provide more context given the lack of structured metadata.

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 all parameters well-documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema, so it meets the baseline of 3 for high schema coverage without adding value.

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 action ('Search') and resource ('bugs across all indexed projects'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'list_bugs' or 'search_tools', but the 'global across all projects' scope provides some implicit 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 like 'list_bugs' or 'get_bug'. It doesn't mention prerequisites, limitations, or appropriate contexts for choosing this search function over other available tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_toolsA

Search for available tools by keyword or category. Use detail_level to control how much information is returned: 'name' for just tool names, 'summary' for names and descriptions, 'full' for complete definitions including input schemas.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoKeyword to search for in tool names, descriptions, and aliases
categoryNoFilter by plugin category (e.g., 'bugtracker')
intentNoFilter by intent category (e.g., 'bug tracking', 'research')
detail_levelNoLevel of detail to return (default: 'summary')summary
include_unavailableNoInclude tools from unavailable plugins (default: false). When true, results include availability status.

TDQS

A3.5/5.0
Behavior3/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 adds useful context about the 'detail_level' parameter's effects (e.g., 'name' for just tool names, 'summary' for names and descriptions, 'full' for complete definitions), which goes beyond the schema. However, it doesn't cover other behavioral aspects like response format, pagination, error handling, or performance characteristics that would be helpful for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: it starts with the core purpose, then immediately provides crucial usage guidance about the 'detail_level' parameter. Every sentence earns its place by adding value, with no redundant or unnecessary information. The structure is clear and efficient.

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 moderate complexity (5 parameters, no output schema, no annotations), the description provides adequate but incomplete context. It explains the purpose and key parameter behavior but lacks information about return values, error conditions, or how results are structured. Without an output schema, the description should ideally provide more guidance on what the tool returns.

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%, so the schema already documents all 5 parameters thoroughly. The description adds some semantic value by explaining the 'detail_level' parameter's impact on returned information, but it doesn't provide additional meaning for other parameters beyond what's in the schema. This meets the baseline of 3 when schema coverage is high.

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: 'Search for available tools by keyword or category.' It specifies the verb ('Search') and resource ('available tools'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'search_bugs_global' or 'web_search', which are also search tools but for different resources.

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 provides some usage context by mentioning the 'detail_level' parameter to control information returned, which implies when to use different levels. However, it doesn't explicitly state when to use this tool versus alternatives like 'search_bugs_global' or 'web_search', nor does it provide exclusions or prerequisites for its use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_bugB

Update an existing bug. Can update status, priority, tags, related_bugs. Supports note-only updates for progress tracking.

ParametersJSON Schema
NameRequiredDescriptionDefault
bug_idYesThe bug ID to update.
statusNoNew status for the bug.
priorityNoNew priority for the bug.
tagsNoNew tags (replaces existing tags).
related_bugsNoRelated bugs (replaces existing).
noteNoNote for the history entry (progress update, reason for change).
project_pathNoPath to project directory (defaults to cwd).

TDQS

B3.2/5.0
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. It mentions 'note-only updates' as a special case and implies field replacement behavior ('replaces existing tags' is in schema, not description). However, it doesn't disclose important behavioral traits like whether updates are atomic, permission requirements, error handling, or what happens when only note is provided without other fields.

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 appropriately concise with two sentences that efficiently convey core functionality. The first sentence states the main purpose and key updatable fields, while the second adds important context about note-only updates. No wasted words, though it could be slightly more structured.

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?

For a mutation tool with 7 parameters, no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and mentions a special case (note-only updates), but lacks important context about behavioral traits, error conditions, and what the tool returns. The 100% schema coverage helps, but the description itself doesn't fully compensate for the lack of annotations and output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value beyond the schema by listing some updatable fields (status, priority, tags, related_bugs) and mentioning note-only updates, but doesn't provide additional semantic context or usage examples beyond what's in the parameter descriptions.

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: 'Update an existing bug' with specific updatable fields (status, priority, tags, related_bugs) and mentions note-only updates. It distinguishes from 'add_bug' (create vs update) but doesn't explicitly differentiate from 'close_bug' which might be a subset operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by stating 'note-only updates for progress tracking' and listing specific updatable fields, suggesting this is for modifying existing bugs. However, it doesn't provide explicit guidance on when to use this vs 'close_bug' or other sibling tools, nor does it mention prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 15 tool updates
    • First observedadd_bug
    • First observedclose_bug
    • First observedconfigure_figma_stories
    • First observedgenerate_user_stories
    • First observedget_bug
    • First observedget_config_status
    • First observedinit_bugtracker
    • First observedlist_bugs
    • First observedlist_categories
    • First observedlist_figma_pages
    • First observedpreview_user_stories
    • First observedsearch_bugs_global
    • First observedsearch_tools
    • First observedupdate_bug
    • First observedweb_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation3/5

The tool set has clear distinct purposes for most tools, but some overlap exists, such as 'close_bug' being a convenience wrapper for 'update_bug', which could cause confusion in selection. However, descriptions help clarify these relationships, and tools like 'configure_figma_stories' and 'generate_user_stories' are well-differentiated within their domain.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern, such as 'add_bug', 'get_bug', 'list_bugs', and 'update_bug', with minor deviations like 'configure_figma_stories' and 'preview_user_stories' that still maintain readability. The naming is largely predictable and coherent across the set.

Tool Count5/5

With 15 tools, the count is well-scoped for a server handling bug tracking, Figma integration, and general utilities. Each tool appears to earn its place by covering specific operations without feeling excessive or thin for the apparent scope of the server.

Completeness4/5

The server provides good coverage for bug tracking with CRUD operations and additional features like searching and configuration. Minor gaps exist, such as no explicit tool for deleting bugs or managing Figma projects beyond the listed operations, but agents can likely work around these with the available tools.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Toolkit

    zxfgds
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
    81
    2
    MIT

  • MCP Server

    sdirishguy
    F
    license
    Not graded
    quality
    C
    maintenance
    A secure Model Context Protocol server providing HTTP endpoints for AI agent tool execution, including file system operations, shell commands, and LLM-based code generation.
    1
    -

  • MCPwner

    nedlir
    A
    license
    Not graded
    quality
    A
    maintenance
    Model Context Protocol server for security research automation, integrating multiple security testing tools into LLM-driven workflows for secret scanning, static analysis, and vulnerability discovery.
    55
    Apache 2.0

Latest Blog Posts

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/agileandy/mcp-secure-server'

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