Skip to main content
Glama
jezweb

Smart Prompts MCP Server

by jezweb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Smart Prompts MCP Server

Tests Coverage Performance Node License

An enhanced MCP (Model Context Protocol) server that fetches prompts from GitHub repositories with intelligent discovery, composition, and management features. This is an enhanced fork of prompts-mcp-server with GitHub integration and advanced features.

🌟 Key Features

Core Capabilities

  • 🔄 GitHub Integration: Fetch prompts directly from GitHub repositories (public/private)

  • 🔍 Smart Discovery: Advanced search with category and tag filtering

  • 🔗 Prompt Composition: Combine multiple prompts into workflows

  • 📊 Usage Tracking: Analytics on prompt usage patterns

  • ⚡ Real-time Updates: Automatic synchronization with GitHub

  • 🤖 AI Guidance: Enhanced tool descriptions and workflow recommendations

MCP Protocol Support

  • Tools: 7 specialized tools for prompt management

  • Resources: 13+ resource endpoints for browsing and discovery

  • Prompts: Dynamic templates with Handlebars support

Related MCP server: code2prompt-mcp

📋 Prerequisites

Before installation, ensure you have:

  • Node.js 18+ installed

  • npm or yarn package manager

  • Git installed and configured

  • GitHub account (for GitHub integration)

  • GitHub Personal Access Token (for private repos or to avoid rate limits)

🚀 Installation

Step 1: Clone and Install

# Clone the repository
git clone https://github.com/jezweb/smart-prompts-mcp.git
cd smart-prompts-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Verify installation
./verify-install.sh

Step 2: Configure Environment

Create a .env file in the project root:

# Required: GitHub Configuration
GITHUB_OWNER=your-username          # Your GitHub username or org
GITHUB_REPO=your-prompts-repo      # Repository containing prompts
GITHUB_BRANCH=main                  # Branch to use (default: main)
GITHUB_PATH=                        # Subdirectory path (optional)
GITHUB_TOKEN=ghp_xxxxx             # Personal access token (recommended)

# Optional: Cache Configuration
CACHE_TTL=300000                    # Cache time-to-live in ms (default: 5 min)
CACHE_REFRESH_INTERVAL=60000        # Auto-refresh interval in ms (default: 1 min)

# Optional: Feature Flags
ENABLE_SEMANTIC_SEARCH=true         # Advanced search features
ENABLE_PROMPT_COMPOSITION=true      # Prompt combination features
ENABLE_USAGE_TRACKING=true          # Track prompt usage

Step 3: MCP Client Configuration

For Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smart-prompts": {
      "command": "node",
      "args": ["/absolute/path/to/smart-prompts-mcp/dist/index.js"],
      "env": {
        "GITHUB_OWNER": "your-username",
        "GITHUB_REPO": "your-prompts-repo",
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

For Roo Cline (VS Code)

Add to Roo Cline MCP settings:

"smart-prompts": {
  "command": "node",
  "args": ["/absolute/path/to/smart-prompts-mcp/dist/index.js"],
  "env": {
    "GITHUB_OWNER": "your-username",
    "GITHUB_REPO": "your-prompts-repo",
    "GITHUB_TOKEN": "ghp_your_token_here"
  }
}

📁 Prompt Organization Best Practices

Recommended Folder Structure

your-prompts-repo/
├── README.md                    # Repository overview
├── ai-prompts/                  # AI and meta-prompts
│   ├── meta-prompt-builder.md
│   └── prompt-engineer.md
├── development/                 # Development prompts
│   ├── backend/
│   │   ├── api-design.md
│   │   └── database-schema.md
│   ├── frontend/
│   │   ├── react-component.md
│   │   └── vue-composition.md
│   └── testing/
│       ├── unit-test-writer.md
│       └── e2e-test-suite.md
├── content-creation/           # Content prompts
│   ├── blog-post-writer.md
│   └── youtube-metadata.md
├── business/                   # Business prompts
│   ├── proposal-generator.md
│   └── email-templates.md
└── INDEX.md                    # Optional: Category index

Naming Conventions

  • Files: Use kebab-case (e.g., api-documentation-generator.md)

  • Prompt Names: Use snake_case in frontmatter (e.g., api_documentation_generator)

  • Categories: Use lowercase with hyphens (e.g., content-creation)

  • Keep names descriptive but concise

📝 Prompt File Format

---
name: api_documentation_generator
title: REST API Documentation Generator
description: Generate comprehensive API documentation with examples
category: documentation
tags: [api, rest, documentation, openapi, swagger]
difficulty: intermediate
author: jezweb
version: 1.0
arguments:
  - name: api_spec
    description: The API specification or endpoint details
    required: true
  - name: format
    description: Output format (markdown, openapi, etc)
    required: false
    default: markdown
---

# API Documentation Generator

Generate comprehensive documentation for {{api_spec}} in {{format}} format.

Include:
- Endpoint descriptions
- Request/response examples
- Authentication details
- Error codes
- Rate limiting information

🛠️ Available Tools

  1. 🔍 search_prompts - Always start here! Search by keyword, category, or tags

  2. 📋 list_prompt_categories - Browse available categories with counts

  3. 📖 get_prompt - Retrieve specific prompt (use exact name from search)

  4. ✨ create_github_prompt - Create new prompts in GitHub

  5. 🔗 compose_prompts - Combine multiple prompts

  6. ❓ prompts_help - Get contextual help and guidance

  7. ✅ check_github_status - Verify GitHub connection

Recommended Workflow

1. search_prompts → Find existing prompts
2. get_prompt → View full content
3. compose_prompts → Combine if needed
4. create_github_prompt → Only if nothing exists

🔧 Troubleshooting

Common Issues

1. "GitHub access failed" Error

# Check your token has repo scope
# Verify token in .env file
GITHUB_TOKEN=ghp_your_actual_token

# Test GitHub access
GITHUB_TOKEN=your_token node test-server.js

2. "Rate limit exceeded" Error

  • Add a GitHub token to increase rate limits

  • Reduce cache refresh interval

  • Use CACHE_TTL to cache longer

3. "No prompts found"

  • Check repository structure matches expected format

  • Verify GITHUB_PATH if using subdirectory

  • Ensure .md files have YAML frontmatter

4. MCP Client Not Connecting

  • Use absolute paths in configuration

  • Check Node.js is in PATH

  • Verify all environment variables

  • Check logs: tail -f ~/.claude/logs/mcp.log

5. Slow Performance

  • Increase CACHE_TTL for less frequent updates

  • Reduce repository size (archive old prompts)

  • Use categories to limit search scope

📈 Scaling Considerations

Current Limitations

  1. GitHub API Rate Limits

    • 60 requests/hour (unauthenticated)

    • 5,000 requests/hour (authenticated)

    • Each directory fetch = 1 request

  2. Search Limitations

    • No native semantic search in GitHub

    • Linear search through all files

    • Performance degrades with 100+ prompts

Scaling Strategies

For 50-200 Prompts

  • ✅ Current implementation works well

  • Use categories and tags for organization

  • Implement local caching

  • Add GitHub token for higher rate limits

For 200-1000 Prompts

  • 🔄 Implement Index File 

    # INDEX.md in repo root
prompts:
  - name: api_generator
    path: development/api-generator.md
    category: development
    tags: [api, codegen]

  • 📊 Add Search Index

    • Generate search index on build

    • Store in search-index.json

    • Update via GitHub Actions

For 1000+ Prompts

  • 🗄️ Database Layer

    • SQLite for local caching

    • Full-text search capabilities

    • Sync with GitHub periodically

  • 🔍 Elasticsearch/Algolia Integration

    • Proper search infrastructure

    • Faceted search

    • Relevance ranking

Future Scaling Features (Roadmap)

  1. Search Index Generation

    • GitHub Action to build index

    • Download single index file

    • Local semantic search

  2. Lazy Loading

    • Fetch categories on demand

    • Progressive enhancement

    • Virtual scrolling for large lists

  3. CDN Support

    • Cache prompts at edge

    • Reduce GitHub API calls

    • Faster global access

🚀 Future MCP Server Ideas

Building on the GitHub integration pattern, here are potential MCP servers:

1. Code Snippets MCP Server

Store and manage reusable code snippets in GitHub

  • Language-specific organization

  • Syntax highlighting

  • Dependency management

  • Version history

2. Documentation Templates MCP

GitHub-based documentation template library

  • README generators

  • API documentation templates

  • Project documentation

  • Auto-generated from code

3. AI Personas MCP Server

Manage AI personality configurations

  • Expertise definitions

  • Communication styles

  • Behavioral traits

  • Team sharing

4. Project Scaffolding MCP

Full project template management

  • Technology stacks

  • Boilerplate code

  • Best practices

  • Configuration presets

5. Learning Resources MCP

Curated educational content

  • Tutorials and guides

  • Code examples

  • Progress tracking

  • Skill-based recommendations

6. Configuration Manager MCP

Version-controlled app configs

  • Environment management

  • Secret handling

  • Team synchronization

  • Rollback support

7. Workflow Automation MCP

GitHub Actions integration

  • Workflow templates

  • CI/CD pipelines

  • Automation scripts

  • Cross-repo orchestration

8. Knowledge Base MCP

Team knowledge management

  • Q&A pairs

  • Troubleshooting guides

  • Best practices

  • Searchable wiki

🧪 Testing

The server includes comprehensive testing to ensure reliability and performance.

Test Suite Features

  • 100% test coverage of critical functionality

  • Performance benchmarks with detailed metrics

  • Visual test reports with interactive charts

  • Automated CI/CD via GitHub Actions

Running Tests

# Run full test suite
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run performance benchmark
npm run test:perf

# Verify installation
npm run test:verify

Test Reports

Test results are automatically generated in multiple formats:

  • JSON: Detailed results for analysis (test-results/latest.json)

  • Markdown: Human-readable reports (test-results/latest.md)

  • HTML: Interactive visual reports (test-results/latest.html)

View the latest test results:

🧪 Development

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Priority Areas

  1. Search Improvements

    • Implement fuzzy search

    • Add search result ranking

    • Support for regex patterns

  2. Performance Optimization

    • Implement connection pooling

    • Add request batching

    • Optimize cache strategies

  3. UI/Visualization

    • Web interface for browsing

    • Prompt preview tool

    • Usage analytics dashboard

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

📞 Support

Available Tools

7 tools
check_github_statusA

Check GitHub connection status and write access. Use this to verify GitHub operations are available.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

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

Describes that it checks both connection and write access, beyond a simple ping. No annotations exist, so description carries full burden; it provides key behavioral traits.

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

Conciseness5/5

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

Two concise sentences with no unnecessary words. Information is front-loaded 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?

Adequate for a simple check tool, but lacks description of the return value or expected output, which would be useful since no output schema exists.

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

Parameters4/5

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

No parameters, so schema coverage is 100%. Description adds meaning by specifying the scope (connection and write access), which is useful context.

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

Purpose5/5

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

Clearly states verb 'Check' and resource 'GitHub connection status and write access'. Differentiates from sibling tools which are all prompt-related.

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

Usage Guidelines4/5

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

Explicitly says 'Use this to verify GitHub operations are available.' providing clear context. No exclusion statements needed as no direct alternative among siblings.

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

compose_promptsA

🔗 Combine Prompts: Combine multiple existing prompts into a single prompt. Perfect for creating complex multi-step workflows. 📋 WORKFLOW: Use search_prompts to find prompt names first, then compose them.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptsYesList of exact prompt names to combine in order. Get these names from search_prompts results. Examples: ["code_review_assistant", "documentation_generator"]
separatorNoText to insert between prompts. Defaults to "\n\n---\n\n". Can use "\n\nNext Step:\n\n" or custom separators.

TDQS

A4.3/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 describes the tool's behavior (combining prompts in order with a separator) and hints at workflow integration, but lacks details on error handling, output format, or limitations (e.g., maximum number of prompts). It doesn't contradict annotations, but could be more comprehensive for a mutation tool.

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

Conciseness4/5

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

The description is front-loaded with the core purpose, followed by usage guidelines. It uses two sentences efficiently, though the emojis and formatting (e.g., '📋 WORKFLOW:') add minor clutter. Overall, it's concise and well-structured for quick comprehension.

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

Completeness4/5

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

Given the tool's moderate complexity (combining prompts), no annotations, and no output schema, the description does a good job covering purpose and usage. However, it lacks details on the output (e.g., what the combined prompt looks like) and potential constraints, leaving some gaps for an agent to infer behavior.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds context by mentioning 'prompt names' and referencing search_prompts, but doesn't provide additional semantic details beyond what's in the schema. Since parameters are well-covered, a baseline of 3 is appropriate, but the workflow reference slightly enhances understanding.

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

Purpose5/5

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

The description clearly states the specific action ('Combine multiple existing prompts into a single prompt') and resource ('prompts'), distinguishing it from siblings like search_prompts (which finds prompts) or get_prompt (which retrieves a single prompt). The emoji and title-like phrasing reinforce the purpose without being tautological.

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

Usage Guidelines5/5

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

It explicitly states when to use this tool ('Perfect for creating complex multi-step workflows') and provides a clear workflow instruction: 'Use search_prompts to find prompt names first, then compose them.' This directly addresses when to use it versus alternatives like search_prompts, offering practical guidance.

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

create_github_promptA

✨ Create New Prompt: Create a new prompt and save it directly to the GitHub repository. 🎯 WORKFLOW: Always use search_prompts first to check if a similar prompt already exists. Only create new prompts when needed to avoid duplicates.

ParametersJSON Schema
NameRequiredDescriptionDefault
argumentsNoTemplate arguments for dynamic content
authorNoAuthor name or handle
categoryNoChoose from existing categories: "development", "content-creation", "business", "ai-prompts", "devops", "documentation", "project-management". Use list_prompt_categories to see all options.
commitMessageNoGit commit message. Defaults to "Add prompt: [name]"
contentYesThe actual prompt template content. Use {{variable_name}} for dynamic placeholders. Include clear instructions and examples in the prompt.
descriptionYesClear, concise description of what the prompt does and when to use it. Include the main benefits and use cases.
difficultyNoComplexity level of the prompt
nameYesUnique identifier for the prompt. Use lowercase with underscores. Examples: "code_review_assistant", "api_documentation_generator", "database_design_helper"
tagsNo2-5 relevant tags for discoverability. Examples: ["code-review", "github", "quality"], ["api", "documentation", "openapi"], ["database", "sql", "design"]
titleYesHuman-readable title that clearly explains the prompt's purpose. Examples: "Code Review Assistant for Pull Requests", "API Documentation Generator", "Database Schema Designer"

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 must disclose behavioral traits. It mentions saving to GitHub but does not explain side effects (e.g., if name already exists, required permissions, or commit default behavior). The workflow mentions duplicate prevention, but more explicit details on mutation and error conditions would improve transparency.

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

Conciseness5/5

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

The description is extremely concise with only two sentences and a workflow label. It is front-loaded with the core purpose and every sentence adds value without redundancy.

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

Completeness4/5

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

Given 10 parameters (4 required) and no output schema, the description plus schema provide sufficient context for usage. The workflow guidance and parameter details are complete, though a brief note on return values or success/failure could enhance completeness.

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 baseline is 3. The input schema already contains detailed descriptions with examples for all parameters. The tool description does not add significant meaning beyond the schema, meriting a score of 3.

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

Purpose5/5

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

The description clearly states 'Create a new prompt and save it directly to the GitHub repository.' This is a specific verb+resource combination that distinguishes the tool from siblings like search_prompts and get_prompt.

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

Usage Guidelines5/5

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

Explicitly states 'Always use search_prompts first to check if a similar prompt already exists. Only create new prompts when needed to avoid duplicates.' This provides clear when-to-use and when-not-to-use guidance, referencing a sibling tool.

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

get_promptA

📖 Get Full Prompt: Retrieve a specific prompt by its exact name. ⚠️ IMPORTANT: Use search_prompts first to find the correct prompt name, then use this tool. Returns the complete prompt content with metadata and template variables.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesExact prompt name from search results. Must match exactly (e.g., "api_documentation_generator", "REST API Endpoint Generator"). Copy the name field from search_prompts results.

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return value ('complete prompt content with metadata and template variables') and includes a caution note ('⚠️ IMPORTANT') about the exact name requirement, adding useful context beyond basic functionality. However, it doesn't mention potential errors or rate limits.

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 front-loaded with the core purpose, followed by important usage guidance and return details. Every sentence adds value with no wasted words, and the emoji and formatting enhance readability without sacrificing clarity.

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

Completeness4/5

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

For a simple retrieval tool with one well-documented parameter and no output schema, the description is largely complete. It explains the purpose, usage workflow, and return content. The main gap is the lack of error handling or edge case information, but overall it provides sufficient 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?

Schema description coverage is 100%, so the schema already documents the single parameter thoroughly. The description reinforces the 'exact name' requirement and references 'search_prompts results,' adding some context but not significant new semantic information beyond what the schema provides.

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

Purpose5/5

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

The description clearly states the verb ('Retrieve') and resource ('a specific prompt by its exact name'), making the purpose specific and actionable. It distinguishes from sibling tools like 'search_prompts' by focusing on retrieval of a single prompt rather than searching or listing.

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

Usage Guidelines5/5

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

The description explicitly provides usage guidance: 'Use search_prompts first to find the correct prompt name, then use this tool.' This specifies a clear workflow and alternative tool, helping the agent understand when and how to use this tool effectively.

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

list_prompt_categoriesA

📋 Overview: List all available prompt categories with prompt counts. Use this to explore the library structure and see what categories exist before searching or creating prompts. Great for discovering new areas.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/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 of behavioral disclosure. It describes the tool's function as listing categories with counts, which is straightforward, but doesn't mention potential behavioral traits like pagination, rate limits, authentication needs, or error handling. For a read-only listing tool with no annotations, this is adequate but lacks depth, justifying a score of 3.

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

Conciseness5/5

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

The description is concise and well-structured: it starts with an overview, states the purpose, and provides usage guidelines in two sentences. Every sentence adds value without redundancy, and it's front-loaded with key information. This earns a score of 5 for efficiency.

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

Completeness3/5

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

Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is reasonably complete for its purpose. It explains what the tool does and when to use it. However, without annotations or an output schema, it could benefit from more details on behavioral aspects or return format, leaving some gaps. This results in a score of 3.

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 parameters need documentation. The description doesn't add parameter information, which is fine in this case. Since there are no parameters, the baseline is 4, as the description doesn't need to compensate for any gaps.

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: 'List all available prompt categories with prompt counts.' It specifies the verb ('list') and resource ('prompt categories'), and includes the additional detail of 'prompt counts.' However, it doesn't explicitly differentiate this from sibling tools like 'search_prompts' or 'get_prompt,' which prevents a score of 5.

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

Usage Guidelines4/5

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

The description provides clear usage context: 'Use this to explore the library structure and see what categories exist before searching or creating prompts. Great for discovering new areas.' This gives guidance on when to use the tool (for exploration and discovery) and implies alternatives (searching or creating prompts). However, it doesn't explicitly state when not to use it or name specific sibling alternatives, so it falls short of a 5.

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

prompts_helpA

Get help understanding how to use the Smart Prompts tools effectively. Returns guidance on tool usage, examples, and best practices.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicNoSpecific topic to get help on (e.g., "creating", "searching", "github", "examples"). Leave empty for general help.

TDQS

A4.3/5.0
Behavior4/5

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

Despite no annotations, the description discloses that the tool returns guidance, examples, and best practices, making its read-only nature obvious.

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

Conciseness5/5

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

The description is a single, efficient sentence with no wasted words.

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

Completeness5/5

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

For a help tool, the description sufficiently explains the tool's purpose and output without needing complex details.

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 coverage is 100% with a clear parameter description; the tool description adds no extra parameter details beyond what the schema provides.

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

Purpose5/5

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

The description clearly states the tool is for getting help on using Smart Prompts tools, distinguishing it from functional siblings like search_prompts and get_prompt.

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

Usage Guidelines4/5

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

The description implies usage when needing guidance on Smart Prompts tools, but does not explicitly exclude or compare with alternatives.

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

search_promptsA

🔍 ALWAYS START HERE: Search for prompts by keyword, category, or tags. Returns matching prompts with their metadata. This is the recommended first step before using get_prompt or creating new prompts. Helps avoid duplicates and find exactly what you need.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoFilter by specific category. Available: "development", "content-creation", "business", "ai-prompts", "devops", "documentation", "project-management"
queryNoSearch keywords to find in prompt title, description, or content. Examples: "api", "documentation", "code review", "testing"
tagsNoFilter by tags for precise matching. Examples: ["api", "rest"], ["testing", "automation"], ["documentation", "technical-writing"]

TDQS

A4.2/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 states this is a search operation that returns metadata, implying it's read-only and non-destructive, which is adequate. However, it lacks details on pagination, rate limits, error handling, or response format, leaving gaps for an AI agent to infer behavior.

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

Conciseness5/5

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

The description is front-loaded with key information ('ALWAYS START HERE') and uses only three sentences, each earning its place by explaining purpose, usage guidelines, and benefits. There is no wasted text, and the structure flows logically from action to context to rationale.

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

Completeness4/5

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

Given the tool's moderate complexity (search with three optional parameters), no annotations, and no output schema, the description is mostly complete. It covers purpose and usage well but lacks details on behavioral aspects like response structure or limitations. It compensates somewhat with strong guidance, but could be more comprehensive for full agent understanding.

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

Parameters3/5

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

The schema description coverage is 100%, so the schema already documents all three parameters (category, query, tags) with examples and constraints. The description adds no additional parameter semantics beyond implying these are search filters, which the schema covers. This meets the baseline for high schema coverage.

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

Purpose5/5

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

The description clearly states the tool's purpose with specific verbs ('search for prompts') and resources ('by keyword, category, or tags'), distinguishing it from siblings like get_prompt (retrieves specific prompts) and create_github_prompt (creates new prompts). It explicitly mentions returning 'matching prompts with their metadata,' providing a complete picture of the operation.

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

Usage Guidelines5/5

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

The description provides explicit guidance on when to use this tool: 'ALWAYS START HERE' and 'recommended first step before using get_prompt or creating new prompts.' It also explains why: 'Helps avoid duplicates and find exactly what you need,' effectively positioning it as a discovery tool versus retrieval or creation alternatives.

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.

  1. 7 tool updatesv1.0.0
    • First observedcheck_github_status
    • First observedcompose_prompts
    • First observedcreate_github_prompt
    • First observedget_prompt
    • First observedlist_prompt_categories
    • First observedprompts_help
    • First observedsearch_prompts
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

Most tools have distinct purposes, such as check_github_status for GitHub connectivity, compose_prompts for combining prompts, and search_prompts for searching. However, get_prompt and search_prompts could be slightly confused since both retrieve prompts, but descriptions clarify that search_prompts is for discovery and get_prompt is for exact retrieval by name.

Naming Consistency4/5

Tool names follow a consistent verb_noun pattern with snake_case throughout, like check_github_status and search_prompts. The only minor deviation is prompts_help, which uses a noun_verb structure, but it still fits the overall naming style and is readable.

Tool Count5/5

With 7 tools, the count is well-scoped for a prompt management server. Each tool serves a clear role, from checking GitHub status to creating, searching, and managing prompts, without feeling bloated or insufficient for the domain.

Completeness4/5

The tool set covers core CRUD operations for prompts, including create_github_prompt, get_prompt, and search_prompts, with additional utilities like compose_prompts and list_prompt_categories. A minor gap is the lack of update or delete tools for prompts, but agents can work around this by creating new prompts as needed.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers