Skip to main content
Glama
jezweb

Smart Prompts MCP Server

by jezweb
OverviewSchemaRelated ServersScoreDiscussions
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

A3.6/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 mentions checking 'connection status and write access,' which implies it performs read operations to verify permissions, but it doesn't disclose behavioral traits like what happens on failure, whether it requires authentication, rate limits, or what the output looks like. 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 two concise sentences with zero waste. The first sentence states the purpose, and the second provides usage guidance, making it front-loaded and efficient. Every sentence earns its place by adding clear value.

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 somewhat complete but lacks depth. It explains what the tool does and when to use it, but without annotations or output schema, it should ideally disclose more about behavior (e.g., what 'write access' means, response format). It's adequate but has clear gaps.

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

Parameters4/5

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

The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for 0 parameters is 4, as the description doesn't need to compensate for any missing schema information, and it appropriately avoids unnecessary parameter discussion.

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: 'Check GitHub connection status and write access.' It specifies both the verb ('Check') and the resources ('GitHub connection status and write access'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools, which are mostly prompt-related, so it doesn't reach a 5.

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

Usage Guidelines4/5

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

The description provides clear context for when to use this tool: 'Use this to verify GitHub operations are available.' This gives a specific scenario (verifying availability before operations) and implies it's a prerequisite check. It doesn't mention when not to use it or name alternatives, so it's not a full 5.

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.1/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 mentions saving 'directly to the GitHub repository' and the duplication-avoidance workflow, which adds useful context beyond basic creation. However, it doesn't cover potential side effects (e.g., GitHub API rate limits, authentication requirements, or error handling), leaving gaps 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 and follows with a clear workflow guideline. Both sentences earn their place by providing essential information. The emojis are slightly decorative but don't significantly impact clarity. It could be slightly more concise by integrating the emojis more seamlessly.

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 complexity (10 parameters, mutation operation) and lack of annotations/output schema, the description does well by specifying the GitHub integration and workflow prerequisites. However, it doesn't fully address behavioral aspects like error conditions or response format, leaving some gaps for a creation tool.

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

Parameters3/5

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

The schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema. This meets the baseline of 3 when the schema does the heavy lifting, but doesn't provide additional semantic context.

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

Purpose5/5

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

The description clearly states the specific action ('Create New Prompt') and resource ('save it directly to the GitHub repository'), distinguishing it from sibling tools like 'search_prompts' or 'get_prompt' which retrieve rather than create. The emojis add emphasis but don't obscure the core purpose.

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 versus alternatives: 'Always use search_prompts first to check if a similar prompt already exists. Only create new prompts when needed to avoid duplicates.' This clearly directs the agent to a specific workflow and names the alternative 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

A3.5/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 discloses that the tool 'Returns guidance on tool usage, examples, and best practices,' which gives some behavioral context about output content. However, it doesn't cover aspects like response format, potential errors, or performance characteristics (e.g., if it's a fast lookup or requires network calls).

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 front-loaded, consisting of two clear sentences that directly state the purpose and output. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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 (1 optional parameter, no output schema, no annotations), the description is moderately complete. It covers the core purpose and output type but lacks details on error handling, response structure, or integration with sibling tools. For a help tool, more context on when and how to use it would improve 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?

The input schema has 100% description coverage, with the 'topic' parameter well-documented in the schema itself. The description doesn't add any parameter-specific information beyond what the schema provides (e.g., it doesn't elaborate on topic examples or constraints). With high schema coverage, the baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Get help understanding how to use the Smart Prompts tools effectively.' It specifies the verb ('Get help') and resource ('Smart Prompts tools'), but doesn't explicitly differentiate from siblings like 'check_github_status' or 'compose_prompts', which are action tools rather than help tools. The purpose is clear but lacks sibling distinction.

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

Usage Guidelines3/5

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

The description implies usage context ('how to use the Smart Prompts tools effectively') but doesn't provide explicit guidance on when to use this tool versus alternatives. For example, it doesn't specify if this should be used before attempting other tools or as a fallback for errors. The guidance is implied rather than explicit.

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.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
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
ResponsivenessSyncing

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

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/jezweb/smart-prompts-mcp'

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