Skip to main content
Glama
deenjakoruzh
gethibiki

Thoth MCP Server

by gethibiki
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Hibiki MCP Server

npm version MCP Registry Smithery License: MIT

Model Context Protocol (MCP) server for Hibiki content creation platform. This server enables AI assistants and tools to create and retrieve content through Hibiki's API.

✨ NEW: Claude Code Plugin now available with slash commands and specialized AI agents for streamlined content creation workflows!

Quick Start

# Install via npx
npx @hibiki/mcp-server --api-key YOUR_API_KEY

# Or configure in Claude Desktop (see Configuration below)

Get your API key at www.gethibiki.com/settings/api-keys

Related MCP server: MCP Server Example

Table of Contents

Features

  • Create Content: Generate platform-optimized content with AI enhancement

  • Retrieve & Manage Posts: Fetch, list, and update post data with pagination

  • Multi-Platform Support: Twitter, Instagram, LinkedIn, Facebook, Threads, Blog, Reddit

  • Brand Styles: Apply consistent voice, tone, and visual styling with brand presets

  • Image Generation: Optionally generate images for your content

  • Scheduling: Schedule posts for future publication

  • Dual Transport: Supports both stdio (local) and HTTP transports (Smithery/cloud deployment)

  • Type-Safe: Built with TypeScript and Zod validation

Claude Code Plugin

NEW! We've created an official Claude Code plugin that makes social media content creation even easier with user-friendly commands and specialized AI agents.

What is it?

The Hibiki plugin for Claude Code provides:

  • 5 Slash Commands: Quick access to common workflows

    • /create-content - Create multi-platform posts with AI guidance

    • /schedule-post - Schedule posts for optimal engagement times

    • /view-brands - Browse and manage your brand styles

    • /manage-posts - List, filter, and manage all your posts

    • /preview-post - Preview platform-specific content formatting

  • 3 Specialized Agents: Expert AI assistants for specific tasks

    • Content Creator - Expert at crafting engaging, platform-optimized content

    • Brand Manager - Ensures brand consistency across all platforms

    • Social Media Optimizer - Maximizes reach and engagement through data-driven strategies

Quick Start with Plugin

# Install the plugin
claude plugin install hibiki

# Set your API key
export HIBIKI_API_KEY="your-api-key-here"

# Start creating content
claude /create-content "Announcing our new feature"

# Or use an agent
claude "Content Creator, help me announce our product launch"

Documentation

Full plugin documentation, installation instructions, and usage examples are available in the claude-code-plugin directory.

See claude-code-plugin/README.md for:

  • Detailed installation instructions

  • Complete command reference

  • Agent usage guides

  • Advanced workflows and examples

  • Troubleshooting tips

Installation

Via MCP Registry (Recommended)

The server is published in the official MCP Registry as io.github.gethibiki/mcp.

Browse and install via the registry web interface, or configure directly in your MCP client (see MCP Client Configuration below).

Via Smithery (Zero-Setup Deployment)

The easiest way to get started is through Smithery, which provides:

  • One-click installation - No local dependencies or configuration needed

  • Automatic updates - Always get the latest version

  • Secure hosting - Your API keys are safely managed

  • Interactive playground - Test tools before using them

Install from Smithery:

  1. Visit the Hibiki MCP Server on Smithery

  2. Click "Install"

  3. Enter your Hibiki API key when prompted

  4. Start using immediately in Claude Desktop or other MCP clients

Global Installation (via npx)

npx @hibiki/mcp-server --api-key YOUR_API_KEY

Local Development

git clone https://github.com/gethibiki/mcp.git
cd hibiki-mcp
pnpm install
pnpm build

Usage

Prerequisites

You'll need a Hibiki API key. Generate one at:

Running the Server

Stdio Mode (Local)

This is the default mode for use with MCP clients like Claude Desktop:

npx @hibiki/mcp-server --api-key YOUR_API_KEY

Or debug with MCP Inspector:

npx @modelcontextprotocol/inspector npx @hibiki/mcp-server --api-key YOUR_API_KEY

With custom base URL:

npx @hibiki/mcp-server \
  --api-key YOUR_API_KEY \
  --base-url https://www.gethibiki.com

Remote HTTP Server Mode

Run the server in HTTP mode for cloud deployments (like Smithery) or to expose the server over HTTP:

npx @hibiki/mcp-server --remote --api-key YOUR_API_KEY

The server will start an HTTP server on port 8081 (configurable via PORT environment variable) with:

  • /mcp - Main MCP endpoint (POST)

  • /health - Health check endpoint (GET)

With custom configuration:

PORT=3000 npx @hibiki/mcp-server \
  --remote \
  --api-key YOUR_API_KEY \
  --base-url https://www.gethibiki.com

Note: In HTTP mode, the server implements MCP Streamable HTTP transport with proper CORS configuration for browser-based clients.

Environment Variables

Instead of command-line flags, you can use environment variables:

For stdio mode:

export HIBIKI_API_KEY=your_api_key
export HIBIKI_BASE_URL=http://localhost:3000
npx @hibiki/mcp-server

For HTTP mode:

export HIBIKI_API_KEY=your_api_key
export HIBIKI_BASE_URL=https://www.gethibiki.com
export PORT=8081
npx @hibiki/mcp-server --remote

Available environment variables:

  • HIBIKI_API_KEY - Your Hibiki API key (stdio mode only; HTTP mode uses query params)

  • HIBIKI_BASE_URL - Base URL for Hibiki API (default: https://www.gethibiki.com)

  • PORT - HTTP server port (HTTP mode only, default: 8081)

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hibiki": {
      "command": "npx",
      "args": [
        "@hibiki/mcp-server",
        "--api-key",
        "YOUR_API_KEY",
        "--base-url",
        "http://localhost:3000"
      ]
    }
  }
}

Other MCP Clients

For other MCP clients that support stdio transport, use a similar configuration with appropriate command and args.

Available Tools

The server provides 6 tools for managing Hibiki content:

Tool

Description

create-post

Create multi-platform content with AI enhancement

get-post

Retrieve a specific post by ID

get-all-posts

List posts with pagination and filtering

update-post

Update existing post title, content, or status

get-brand-styles

List all available brand styles

get-brand-style

Get detailed brand style configuration

create-post

Create a new content post with platform-specific variations.

Parameters:

  • content (required): The original content to be enhanced

  • platforms (required): Array of target platforms

    • Options: twitter, instagram, linkedin, facebook, threads, blog, reddit

  • length (optional): Content length - very-short, short, medium, long (default: medium)

  • createImage (optional): Generate an image (default: false)

  • createHashtags (optional): Generate hashtags (default: true)

  • scheduleTime (optional): ISO 8601 datetime to schedule the post

  • postToSocialNetworks (optional): Immediately post to connected networks (default: false)

  • brandStyleId (optional): Brand style UUID to apply

Example:

{
  "content": "Just launched our new AI-powered content creation tool!",
  "platforms": ["twitter", "linkedin"],
  "length": "medium",
  "createImage": true,
  "createHashtags": true
}

Returns:

  • Post ID

  • Original content

  • Platform-specific enhanced content

  • Generated images (if requested)

  • Hashtags for each platform

  • Status and timestamps

get-post

Retrieve a post by its ID.

Parameters:

  • postId (required): UUID of the post

Example:

{
  "postId": "123e4567-e89b-12d3-a456-426614174000"
}

Returns:

  • Complete post data

  • Platform-specific content

  • Generated images

  • Status and metadata

get-all-posts

List all posts with pagination and filtering.

Parameters:

  • page (optional): Page number (default: 1)

  • limit (optional): Posts per page (default: 10)

  • status (optional): Filter by status - draft, scheduled, published

Example:

{
  "page": 1,
  "limit": 20,
  "status": "published"
}

Returns:

  • Array of posts with metadata

  • Pagination information

  • Total count

update-post

Update an existing post.

Parameters:

  • postId (required): UUID of the post to update

  • title (optional): New title for the post

  • content (optional): New content

  • status (optional): New status - draft, scheduled, published

Example:

{
  "postId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Updated Title",
  "status": "published"
}

Returns:

  • Updated post data

  • Confirmation message

get-brand-styles

List all available brand styles for your account.

Parameters: None

Returns:

  • Array of brand styles with IDs and names

  • Style metadata

get-brand-style

Get details for a specific brand style.

Parameters:

  • brandStyleId (required): UUID of the brand style

Example:

{
  "brandStyleId": "123e4567-e89b-12d3-a456-426614174000"
}

Returns:

  • Brand style name and description

  • Color palette

  • Typography settings

  • Tone and voice guidelines

  • Imagery preferences

Available Resources

post://{postId}

Access post data as an MCP resource.

Example URI:

post://123e4567-e89b-12d3-a456-426614174000

preview://{postId}/{platform}

Get platform-specific preview content.

Example URI:

preview://123e4567-e89b-12d3-a456-426614174000/twitter

Development

Building

pnpm build

Running Locally

pnpm start -- --api-key YOUR_API_KEY

Type Checking

pnpm typecheck

Development Mode (Watch)

pnpm dev

API Integration

The MCP server connects to Hibiki's REST API endpoints:

  • POST /api/v1/posts - Create new posts

  • GET /api/v1/posts/{postId} - Retrieve single post

  • GET /api/v1/posts - List posts with pagination

  • PUT /api/v1/posts/{postId} - Update existing post

  • GET /api/v1/brand-styles - List brand styles

  • GET /api/v1/brand-styles/{brandStyleId} - Get brand style details

All requests require the X-API-Key header for authentication.

Error Handling

The server provides detailed error messages for common issues:

  • Invalid API Key: Check your API key is correct and active

  • Rate Limit Exceeded: Wait before making additional requests

  • Post Not Found: Verify the post ID is correct

  • Invalid Parameters: Check parameter types and formats

  • Network Errors: Verify the base URL and network connection

Examples

Creating a Multi-Platform Post

// Using the create-post tool
{
  "content": "Excited to share our latest feature! \ud83d\ude80 AI-powered content optimization for all your social platforms.",
  "platforms": ["twitter", "linkedin", "instagram"],
  "length": "medium",
  "createImage": true,
  "createHashtags": true
}

Scheduling a Post

{
  "content": "Join us for our product launch next week!",
  "platforms": ["twitter", "linkedin"],
  "scheduleTime": "2025-10-20T14:00:00Z",
  "createImage": true
}

Retrieving Post Data

// Using the get-post tool
{
  "postId": "123e4567-e89b-12d3-a456-426614174000"
}

Accessing Resources

// Read post resource
{
  "uri": "post://123e4567-e89b-12d3-a456-426614174000"
}

// Read platform-specific preview
{
  "uri": "preview://123e4567-e89b-12d3-a456-426614174000/twitter"
}

Testing HTTP Mode Locally

Start the server in HTTP mode:

npx @hibiki/mcp-server --remote --api-key YOUR_API_KEY

Test the health endpoint:

curl http://localhost:8081/health

Test the MCP endpoint with MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:8081/mcp?apiKey=YOUR_API_KEY

Or use with a Streamable HTTP MCP client that supports query-based configuration.

Troubleshooting

Server won't start

  • Check that you have Node.js 18+ installed

  • Verify your API key is valid

  • Ensure the base URL is correct and accessible

Tool calls fail

  • Verify your API key has the required permissions

  • Check rate limits haven't been exceeded

  • Ensure post IDs are valid UUIDs

  • Verify platform names are spelled correctly

HTTP mode not accessible

  • Check the port isn't already in use: lsof -i :8081 (or your configured PORT)

  • Verify firewall settings allow the connection

  • Ensure the server process is running with the --remote flag

  • Check the server logs for any startup errors

  • Verify the /health endpoint responds: curl http://localhost:8081/health

  • For Smithery deployments, check the deployment logs in the Smithery dashboard

Smithery deployment fails

  • Ensure your GitHub repository is public or connected to Smithery

  • Verify smithery.yaml and Dockerfile are in the repository root

  • Check the build logs in Smithery dashboard for specific errors

  • Ensure all dependencies are declared in package.json

  • Try building the Docker image locally: docker build -t hibiki-mcp .

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Please ensure your code:

  • Follows the existing TypeScript style

  • Includes appropriate Zod schemas for validation

  • Updates documentation as needed

  • Passes type checking (pnpm typecheck)

  • Uses console.error() for logging (not console.log() - it breaks stdio mode)

For Maintainers

See PUBLISHING.md for detailed instructions on building and publishing updates.

Support

License

MIT License - see the LICENSE file for details.

Changelog

v1.3.0 (2025-10-10)

  • NEW: Added official Claude Code plugin

  • NEW: 5 slash commands for streamlined content workflows

  • NEW: 3 specialized AI agents (Content Creator, Brand Manager, Social Media Optimizer)

  • Plugin provides user-friendly interface to all MCP server capabilities

  • Comprehensive plugin documentation and usage examples

  • Enhanced developer experience for Claude Code users

v1.2.0 (2025-10-08)

  • NEW: Added HTTP transport support for Smithery and cloud deployments

  • NEW: Implemented MCP Streamable HTTP with /mcp and /health endpoints

  • Server now supports dual transport modes: stdio (local) and HTTP (remote)

  • Added Express and CORS dependencies for HTTP server

  • Added Dockerfile for containerized deployment

  • Configured for Smithery deployment with proper HTTP runtime

  • HTTP mode supports configuration via query parameters

  • Maintains backward compatibility with stdio mode for Claude Desktop

v1.0.3 (2025-10-08)

  • Added comprehensive publishing documentation (PUBLISHING.md)

  • Removed all debug console logs from config

  • Improved contributor guidelines

v1.0.2 (2025-10-08)

  • CRITICAL FIX: Removed console.log statements breaking stdio JSON-RPC protocol

  • Changed debug output to stderr to prevent JSON parsing errors

  • Server now works correctly with Claude Desktop and other MCP clients

v1.0.1 (2025-10-08)

  • Published to official MCP Registry

  • Updated package metadata

  • Complete tool documentation

v1.0.0 (2025-10-08)

  • Initial release

  • Support for 6 Hibiki API tools

  • Multi-platform content creation

  • Brand style integration

Available Tools

6 tools
create-postA

Create a new content post with platform-specific variations. Enhances the content for each platform, optionally generates images, and can schedule or publish to social networks.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesThe original content to be enhanced and posted
platformsYesTarget platforms for the content
scheduleTimeNoOptional ISO 8601 datetime to schedule the post
createImageNoWhether to generate an image for the post
lengthNoDesired content length
createHashtagsNoWhether to generate hashtags for the content
postToSocialNetworksNoWhether to immediately post to connected social networks
brandStyleIdNoOptional brand style ID to apply to the content

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries full burden. It discloses that it enhances content, generates images, schedules, and publishes. However, it lacks details on side effects, authentication needs, rate limits, or error 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 concise with two sentences. It front-loads the primary purpose and adds key details without fluff.

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 8 parameters and no output schema, the description covers the overall function but lacks depth on parameter interactions, such as scheduling versus immediate posting or handling of optional features. It is adequate but not fully comprehensive.

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 description adds minimal new meaning beyond the schema, e.g., 'enhances the content for each platform' provides context but does not detail parameter semantics.

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 creates a new content post with platform-specific variations. It distinguishes from sibling tools like get-all-posts, get-post, and update-post, which are read or update operations.

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 for creating posts, but does not explicitly state when to use it versus alternatives, nor does it provide when-not-to-use guidance. No exclusions or prerequisites are mentioned.

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

get-all-postsA

Retrieve all posts with pagination and optional filtering by status. Returns a list of posts with their metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoPage number for pagination (default: 1)
limitNoNumber of posts per page (default: 10, max: 100)
statusNoFilter posts by status

TDQS

A3.6/5.0
Behavior2/5

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

No annotations provided; description only mentions pagination/filtering. Lacks disclosure of rate limits, permission requirements, or safety guarantees for a read operation.

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?

Single, well-structured sentence. No extraneous words; all information earns its place.

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?

With full schema coverage and no output schema, description covers pagination, filtering, and return type. Could specify 'metadata' details (e.g., id, title, dates) but sufficient.

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%, so baseline is 3. Description adds no new meaning beyond schema—e.g., 'optional filtering by status' is redundant.

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?

Clear verb 'Retrieve', resource 'all posts', and features (pagination, optional filtering). Distinguishes from siblings like 'get-post' which targets a single post.

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?

Implies usage for listing posts, but no explicit when-to-use or when-not-to-use compared to siblings like 'get-post' or search alternatives.

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

get-brand-styleA

Retrieve a specific brand style by ID with full details including colors, tone, and imagery style.

ParametersJSON Schema
NameRequiredDescriptionDefault
brandStyleIdYesThe unique identifier of the brand style

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description must disclose behavior. It indicates a read operation but lacks details on error handling (e.g., not found), response structure, or authentication requirements.

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?

Single sentence, no unnecessary words, front-loaded with verb and resource.

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?

Simple tool with one parameter, description covers key fields returned, adequate for a basic get operation; missing output schema info but acceptable.

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%, and the description adds no additional meaning beyond 'by ID' which is already in the schema's description of brandStyleId.

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 the tool retrieves a specific brand style by ID with full details including colors, tone, and imagery style, distinguishing it from sibling tools like get-brand-styles.

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?

Implied usage (when you need a single brand style by ID) but no explicit guidance on when not to use or alternatives among siblings.

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

get-brand-stylesA

Retrieve all brand styles for the authenticated user. Returns a list of brand styles with their basic information.

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?

Discloses that it returns a list with basic information for the authenticated user, but lacks details on pagination, performance, or any side effects. With no annotations, more depth would be helpful.

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 that front-load the action. No unnecessary words, every sentence earns its place.

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?

Adequate for a simple tool with no parameters and no output schema. It could be improved by specifying the structure of 'basic information', but overall 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?

Input schema is empty, so the description adds value by noting 'authenticated user' and that the return is a list of brand styles with basic information. This provides context beyond the schema.

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 action 'Retrieve all brand styles' and specifies the resource and scope. It naturally distinguishes from the sibling tool 'get-brand-style' (singular) by emphasizing 'all'.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like 'get-brand-style'. Missing explicit usage context or exclusions.

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

get-postA

Retrieve a post by its ID. Returns the original content, platform-specific variations, generated images, and metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
postIdYesThe UUID of the post to retrieve

TDQS

A3.5/5.0
Behavior2/5

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

With no annotations, the description carries the burden of behavioral transparency. It implies read-only via 'retrieve,' but does not explicitly state no side effects, authentication needs, or rate limits. This is minimal for a read operation.

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 a single sentence covering purpose and return details. It is concise but could benefit from a brief bullet-like structure. No wasted words.

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

Completeness4/5

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

Given the tool's simplicity (one parameter, no output schema), the description adequately explains what is returned. For a read operation, it is reasonably complete.

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%, and the description aligns with the parameter by saying 'by its ID.' No additional parameter semantics are added 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 action ('Retrieve a post by its ID'), specifies the resource ('post'), and lists the returned components, distinguishing it from sibling tools like get-all-posts or create-post.

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?

No explicit guidance on when to use this tool versus alternatives; usage is implied by the purpose and sibling context, but no when-not or alternative delineation is provided.

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

update-postB

Update an existing post. Can modify title, content, platform-specific variations, and status.

ParametersJSON Schema
NameRequiredDescriptionDefault
postIdYesThe UUID of the post to update
titleNoUpdated title for the post
originalContentNoUpdated original content
platformContentsNoUpdated platform-specific content variations
statusNoUpdated post status

TDQS

B3.3/5.0
Behavior2/5

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

No annotations provided, so description must fully disclose behavior. Only states 'Update' without specifying merge vs replace, side effects, idempotency, or permissions. Major 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?

One sentence, 12 words, front-loaded with purpose. Efficient, but could include more behavioral details without sacrificing conciseness.

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

Completeness2/5

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

5 parameters, 1 required, 1 enum, 1 nested object, no output schema. Description lacks details on partial updates, return value, and behavior. Incomplete for the complexity.

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%, so baseline is 3. Description adds marginal value by listing field categories, but schema already describes each parameter.

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 the verb 'Update' and the resource 'existing post'. Lists modifiable fields. Distinguishes from siblings: create-post, get-post, get-all-posts, etc.

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?

Implies usage for updating posts but gives no explicit when-to-use or when-not-to-use, nor alternatives. Only a single sentence without context.

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. 6 tool updatesv1.1.4
    • First observedcreate-post
    • First observedget-all-posts
    • First observedget-brand-style
    • First observedget-brand-styles
    • First observedget-post
    • First observedupdate-post
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.8/5.0

Scored across 6 tools

Disambiguation5/5

Tools are clearly divided into two distinct domains: posts (create-post, get-all-posts, get-post, update-post) and brand styles (get-brand-style, get-brand-styles). No overlap in purpose, ensuring easy differentiation.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, e.g., create-post, get-brand-styles, update-post. No mixing of conventions.

Tool Count5/5

With 6 tools, the set is well-scoped for a content management server, covering essential operations on posts and brand styles without unnecessary bloat.

Completeness3/5

Posts have create, read (single/list), and update but lack delete. Brand styles only have read operations (single/list), missing create, update, and delete. These gaps may hinder full lifecycle management.

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers