Skip to main content
Glama
hmcts

Smart Prompts MCP Server

by hmcts
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/hmcts/ai-in-sdlc-smart-prompts-mcp.git
cd ai-in-sdlc-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/ai-in-sdlc-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/toai-in-sdlc-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 description carries full burden. It states the combine behavior but does not disclose what the tool returns (e.g., combined text, new prompt resource) or any side effects. Adequate but lacks detail.

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?

Description is two sentences plus a workflow note, front-loaded with purpose and emoji. No wasted words.

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?

Covers purpose and workflow but lacks return value description. For a simple tool with no output schema, this omission reduces completeness.

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 coverage is 100%, so baseline is 3. Description adds value by instructing to get prompt names from search_prompts and provides examples, exceeding schema descriptions.

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?

Description clearly states 'Combine multiple existing prompts into a single prompt,' which is a specific verb+resource. It distinguishes from sibling tools like search_prompts (searching) and get_prompt (single 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 mentions 'Perfect for creating complex multi-step workflows' and provides a workflow: 'Use search_prompts to find prompt names first.' This gives clear when-to-use and prerequisite 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
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"
authorNoAuthor name or handle
contentYesThe actual prompt template content. Use {{variable_name}} for dynamic placeholders. Include clear instructions and examples in the prompt.
categoryNoChoose from existing categories: "development", "content-creation", "business", "ai-prompts", "devops", "documentation", "project-management". Use list_prompt_categories to see all options.
argumentsNoTemplate arguments for dynamic content
difficultyNoComplexity level of the prompt
descriptionYesClear, concise description of what the prompt does and when to use it. Include the main benefits and use cases.
commitMessageNoGit commit message. Defaults to "Add prompt: [name]"

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.2/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It states returns 'complete prompt content with metadata and template variables'. This is sufficient for a read-only retrieval. No contradictions or omissions.

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 sentences, no fluff. First sentence states purpose, second provides critical prerequisite. Efficient and front-loaded.

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 simplicity of the tool (one parameter, no output schema), the description covers purpose, usage, and behavior adequately. Could mention error cases like 'not found' but not necessary for 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% and the parameter description in schema is detailed. The tool description does not add extra parameter meaning beyond the schema, so baseline score of 3 is appropriate.

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 retrieves a specific prompt by exact name, using strong verb 'Retrieve' and specifying the resource. It distinguishes from sibling search_prompts by emphasizing use after searching.

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 instructs to use search_prompts first to find the correct name. Does not explicitly state when not to use, but the sequential workflow is clear. Could improve by mentioning alternatives or conditions.

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

A4.4/5.0
Behavior4/5

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

No annotations, but description implies read-only (explore, browse). States it returns categories with counts. Clearly safe and non-destructive.

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 sentences, no waste. First sentence states purpose, second provides usage context. Well-structured and front-loaded.

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 simplicity (0 params, no output schema), description covers purpose and usage adequately. Mentions return includes prompt counts. Could detail output structure but sufficient.

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?

Zero parameters, so baseline is 4. Schema description 'No parameters needed' covers it. Description reinforces no params needed.

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?

Specific verb 'List' and resource 'prompt categories' with 'prompt counts'. Distinguishes from sibling tools like search_prompts (search within categories) and create_github_prompt (creation).

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 explore... before searching or creating prompts', providing clear context. Does not explicitly state when not to use, but implies alternatives.

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

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 the full burden for behavioral traits. It implies the tool is safe (returns data, no side effects) but does not explicitly state it is read-only, lacks destructive consequences, or outline any rate limits. For a search tool, the description is adequate but not fully transparent.

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—three short sentences. It front-loads the critical usage guidance ('ALWAYS START HERE') and eliminates any unnecessary words. Every sentence adds value.

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 has only three optional parameters, 100% schema coverage, no output schema, and no annotations, the description is largely complete. It explains the tool's role and what it returns. However, it could optionally mention that results might be paginated or include sorting, but this is not a critical omission.

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 covers 100% of parameters with detailed descriptions and examples. The tool description adds minimal new value beyond mentioning 'keyword, category, or tags,' which aligns with the schema. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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 uses a specific verb 'Search' and resource 'prompts' with clear filtering criteria (keyword, category, tags). It explicitly distinguishes from siblings (get_prompt, create_github_prompt) by recommending this as the first step, making its purpose clear and differentiated.

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 'ALWAYS START HERE' and 'recommended first step before using get_prompt or creating new prompts,' providing clear guidance on when to use the tool and how it fits into the workflow (avoiding duplicates).

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 updatesv3.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

A4.3/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: help, list categories, search, get, create, check status, and compose. No overlap; descriptions clarify workflow order.

Naming Consistency4/5

Most tools follow verb_noun snake_case (list_prompt_categories, search_prompts, get_prompt, etc.), but 'prompts_help' reverses to noun_verb, breaking the pattern.

Tool Count5/5

7 tools is well-scoped for a prompt management server: discovery, retrieval, creation, composition, and status checking. Not too few or too many.

Completeness3/5

Covers discovery, retrieval, creation, and composition, but lacks update, delete, or list-all prompts, leaving notable gaps for full lifecycle management.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers