Skip to main content
Glama
ckaraca
by ckaraca

Fake Store MCP Server

NPM Version License: MIT

A Model Context Protocol (MCP) server that provides AI assistants like Claude with access to the Fake Store API - a free REST API for e-commerce prototyping and testing.

Features

  • 9 Ready-to-Use Tools for products, carts, and users

  • Full TypeScript Support with strict type safety

  • Production-Ready with retry logic and error handling

  • Zero Configuration - works out of the box

  • Beginner-Friendly - great for learning MCP development

Related MCP server: Fake Store API MCP Server

Available Tools

Products

  • list_products - Get all products with pagination and sorting

  • get_product - Get detailed product information by ID

  • list_categories - Get all available product categories

  • get_products_by_category - Filter products by category

Carts

  • list_carts - Get all shopping carts

  • get_cart - Get cart details by ID

  • get_user_carts - Get all carts for a specific user

Users

  • list_users - Get all users

  • get_user - Get user details by ID

Installation

For Claude Desktop

  1. Install the package:

npm install -g fake-store-mcp
  1. Configure Claude Desktop:

Edit your Claude Desktop configuration file:

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

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "fake-store": {
      "command": "npx",
      "args": ["-y", "fake-store-mcp"]
    }
  }
}

Alternative (if installed globally):

{
  "mcpServers": {
    "fake-store": {
      "command": "fake-store-mcp"
    }
  }
}
  1. Restart Claude Desktop

The tools will now be available in your Claude conversations!

For Other MCP Clients

If you're using another MCP-compatible client, you can run the server directly:

npx fake-store-mcp

Or install it locally in your project:

npm install fake-store-mcp

Usage Examples

Example 1: Browsing Products

User: "Show me the first 5 products from the store"

Claude: Uses list_products tool with limit: 5

User: "What electronics products are available?"

Claude: Uses list_categories first, then get_products_by_category with category: "electronics"

Example 3: User Cart Analysis

User: "Show me what user 1 has in their shopping carts"

Claude: Uses get_user_carts with userId: 1

Example 4: Product Details

User: "Tell me more about product ID 5"

Claude: Uses get_product with id: 5

Tool Parameters

list_products

{
  limit?: number;      // Limit number of results
  sort?: 'asc' | 'desc'; // Sort order
}

get_product

{
  id: number;          // Product ID (required)
}

list_categories

No parameters required.

get_products_by_category

{
  category: string;    // Category name (required)
  limit?: number;      // Limit number of results
  sort?: 'asc' | 'desc'; // Sort order
}

list_carts

{
  limit?: number;      // Limit number of results
  sort?: 'asc' | 'desc'; // Sort order
}

get_cart

{
  id: number;          // Cart ID (required)
}

get_user_carts

{
  userId: number;      // User ID (required)
}

list_users

{
  limit?: number;      // Limit number of results
  sort?: 'asc' | 'desc'; // Sort order
}

get_user

{
  id: number;          // User ID (required)
}

Development

Prerequisites

  • Node.js 18 or higher

  • npm or yarn

Setup

# Clone the repository
git clone https://github.com/ckaraca/fake-store-mcp.git
cd fake-store-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (auto-rebuild on changes)
npm run dev

Project Structure

fake-store-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── products.ts       # Product tools
│   │   ├── carts.ts          # Cart tools
│   │   └── users.ts          # User tools
│   ├── api/
│   │   ├── client.ts         # HTTP client with retry logic
│   │   └── types.ts          # TypeScript type definitions
│   └── utils/
│       └── error-handler.ts  # Error handling utilities
├── dist/                     # Compiled output
└── package.json

Contributing

Contributions are welcome! This project is designed to be beginner-friendly and serves as a reference for learning MCP server development.

How to Contribute

  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

License

MIT License - see the LICENSE file for details.

About Fake Store API

This server integrates with fakestoreapi.com, a free REST API for e-commerce testing and prototyping. The API provides:

  • 20 sample products across 4 categories

  • 10 sample users

  • 7 sample shopping carts

  • No authentication required

  • No rate limits

Resources

Troubleshooting

Server not showing in Claude Desktop

  1. Verify the configuration file path is correct

  2. Ensure the JSON is valid (no trailing commas)

  3. Restart Claude Desktop completely

  4. Check Claude Desktop logs for errors

"Command not found" error

Make sure the package is installed globally:

npm install -g fake-store-mcp

Network errors

The server requires internet access to reach fakestoreapi.com. Check your network connection and firewall settings.

Acknowledgments


Made with ❤️ for the MCP community

If you find this useful, please give it a ⭐️ on GitHub!

Available Tools

9 tools
get_cartA

Get detailed information about a specific cart by its ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

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 full burden, but it only says 'Get detailed information' without specifying return shape, side effects, or any constraints. It does not disclose what 'detailed' includes or any behavioral traits like read-only status or pagination.

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, focused sentence with no filler or redundancy.

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

Completeness3/5

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

For a simple get-by-ID tool, the description is adequate, but it lacks detail on what the response contains and doesn't clarify when to use this over get_user_carts. Given no output schema, more specificity about return values 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 schema's single parameter 'id' is self-explanatory, and the description confirms it's the cart's ID. However, no additional meaning like format or constraints beyond the schema is provided.

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 ('Get') and resource ('cart') with scope ('by its ID'), clearly distinguishing it from sibling list tools like list_carts and get_user_carts.

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 when you have a cart's ID, but doesn't explicitly state when to prefer this over list_carts or get_user_carts. No exclusion criteria or alternatives are mentioned.

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

get_productB

Get detailed information about a specific product by its ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, and the description simply states the basic operation without disclosing behavior like response structure, error handling, or read-only nature. It does not add contextual information beyond what the tool name already conveys.

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

Conciseness5/5

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

The description is a single, direct sentence with no unnecessary words or repetition. It is perfectly concise and front-loaded with the essential verb and object.

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?

While the tool is simple (one parameter, no output schema), the description lacks details about what 'detailed information' includes, error behavior, or any limitations. However, for a basic get-by-id operation, it remains minimally viable since the purpose and parameter are clearly stated.

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

Parameters2/5

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

The description mentions 'by its ID', which ties the id parameter to the product identifier, but the schema's property name already does this. With 0% schema description coverage, the description fails to provide any additional semantic detail about the parameter, such as format expectations or edge cases.

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 (get), the resource (detailed information about a specific product), and the identifier (by its ID). This distinctly separates it from sibling tools that list or filter products, as it is specifically retrieving a single product.

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 when you have a product ID and need detailed data, but it does not explicitly provide any exclusion criteria or mention alternative tools such as list_products or get_products_by_category. Guidance is present but not elaborated.

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

get_products_by_categoryA

Get all products in a specific category. Supports pagination with limit and sorting.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNo
limitNo
categoryYes

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 must carry the behavioral disclosure burden. It mentions pagination and sorting, which adds useful context, but it does not cover edge cases like missing categories, default limits, or sort field applicability.

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, front-loaded with the primary purpose, followed by a brief note on pagination and sorting. No redundant or filler content.

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 low-complexity read tool with no output schema and no annotations, the description covers the core purpose, required category, and optional pagination/sorting behavior. It is slightly incomplete regarding defaults and error behavior, but sufficient for a simple tool.

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?

Despite 0% schema coverage, the description adds meaning by explaining 'pagination with limit' and 'sorting', directly clarifying the purpose of the limit and sort parameters. 'Specific category' also frames the required category 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?

The description states 'Get all products in a specific category' with a clear verb and resource, distinguishing it from sibling tools like list_products (all products) and get_product (single product).

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 explicit guidance is given about when to use this tool versus alternatives. It implies use for category filtering but does not mention list_products or other tools, nor any exclusions.

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

get_userB

Get detailed information about a specific user by their ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

B3.3/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 only says 'Get detailed information' without disclosing return format, error behavior (e.g., 404 if user not found), or authentication requirements. This is a significant transparency gap for a getter with no structured annotations.

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, tightly worded sentence that says exactly what the tool does. No filler, redundancy, or unnecessary details.

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?

With no output schema or annotations, the description is the only source of context. It adequately conveys the basic function but lacks detail about the response contents or potential failure modes. For a simple getter, this is minimally acceptable but not rich.

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 defines the required 'id' parameter as an integer >0, but provides no description. The description adds that it is the 'user's ID,' giving minimal context. However, it does not explain how to obtain the ID or any constraints beyond what the schema already states.

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 ('Get'), the resource ('user'), and the scope ('specific user by their ID'). It distinguishes this from sibling tools like list_users (which lists all users) and get_user_carts (which retrieves carts), so the purpose is unmistakable.

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

Usage Guidelines2/5

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

The description gives no guidance on when to use this tool vs alternatives. It does not mention that you need a user ID obtained from list_users, nor does it exclude cases like user carts. The user is left to infer usage context.

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

get_user_cartsA

Get all shopping carts for a specific user by their user ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
userIdYes

TDQS

A4.2/5.0
Behavior3/5

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

There are no annotations provided, so the description carries the full burden of behavioral disclosure. The word 'Get' implies a read-only operation, which is safe, but the description doesn't mention what happens if the user doesn't exist, the return format, or whether an empty list is returned. This is acceptable for a simple retrieval tool but lacks explicit behavioral context.

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, concise sentence that is front-loaded with the action and resource. Every word earns its place, with no extraneous content.

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 provides enough context to understand its core purpose. However, it doesn't mention the return structure or edge cases, which would enhance completeness. It's still fairly complete for a straightforward read operation.

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 only one parameter, userId (integer >0), with 0% schema description coverage. The description compensates by explicitly stating 'by their user ID', which clarifies the parameter's purpose and meaning. This adds value beyond the schema, though it could be more explicit about the expected format or origin of the ID.

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 'Get all shopping carts for a specific user by their user ID' uses a specific verb ('Get') and resource ('shopping carts') with a clear scope ('for a specific user'). It distinguishes itself from siblings like list_carts (which likely returns all carts) and get_cart (which likely returns a single cart).

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 clearly states that this tool retrieves carts for a specific user, implying it should be used when you have a user ID and need that user's carts. However, it does not explicitly mention alternatives or exclusions (e.g., when to use list_carts or get_cart), 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.

list_cartsA

Get all shopping carts. Supports pagination with limit and sorting.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNo
limitNo

TDQS

A3.7/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 does mention pagination and sorting, which is useful, but it omits details such as the sort field, default ordering, response format, or read-only nature.

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 short sentences with no filler. The first sentence states the purpose, and the second adds behaviorally relevant capability info, making it appropriately sized and front-loaded.

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?

This is a simple list tool with two optional parameters, but with no output schema or annotations, the description is somewhat thin. It does not explain return shape, default sort field, pagination behavior (e.g., max limit), or how it relates to scoped list tools like get_user_carts.

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 0% description coverage, so the description must compensate. It associates 'limit' with pagination and references sorting, but it does not explain what field sorting applies to or any defaults. This adds minimal meaning beyond the parameter names.

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 the specific verb 'Get' with the resource 'all shopping carts', clearly indicating a list-all operation. It distinguishes from siblings like get_cart (single cart) and get_user_carts (scoped to a user) through the word 'all'.

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 notes pagination with limit and sorting, providing some usage context, but it does not explicitly state when to prefer this tool over alternatives like get_cart or get_user_carts. No exclusions or alternative tool references are provided.

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

list_categoriesA

Get all available product categories.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and resource, without mentioning read-only implications, auth requirements, pagination, or any side effects, offering minimal transparency beyond what the name implies.

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 concise sentence that clearly and directly states the tool's purpose. Every word earns its place, with no unnecessary information or 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 the simplicity of the tool (no parameters, no output schema), the description is reasonably complete for a basic list operation. However, it could have provided more context about the return format or any inherent ordering/filtering, but for a simple category list, it is adequate.

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 zero parameters, so the schema imposes no requirements. The description doesn't add parameter details, but the baseline for 0 params is 4, indicating the description adequately covers the trivial parameter 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 action ('Get all available product categories') with a specific verb and resource. It distinguishes itself from sibling tools like list_products and get_products_by_category by specifying the target is categories, not products.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of use cases, exclusions, or references to sibling tools, leaving the agent without context for choosing this tool over similar list operations.

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

list_productsA

Get all products from the store. Supports pagination with limit and sorting.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNo
limitNo

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It mentions pagination and sorting as behavioral capabilities, which is useful context, but it does not explicitly state that the operation is read-only, whether authentication is required, or the potential for large result sets. The 'get' verb implies read-only but is not explicit.

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 front-load the core action with no unnecessary detail. Every word contributes to the essential meaning.

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

Completeness3/5

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

For a simple list tool with no output schema, the description covers the basic operation but lacks details about return format, default pagination, or how it differs from sibling product tools. It is minimally viable but leaves clear gaps for an agent choosing among tools.

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

Parameters3/5

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

The schema has no parameter descriptions (0% coverage), so the description partially compensates by mentioning 'limit' and 'sorting'. It clarifies that limit supports pagination and that sorting is available, but it does not explain the sort enum values, the field being sorted, or default limit behavior.

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 all products from the store, using a specific verb and resource. It distinguishes from sibling tools like get_product (single product) and get_products_by_category (filtered products) 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 explicit guidance is provided on when to use this tool versus alternatives such as get_product or get_products_by_category. The phrase 'Get all products' implies a general list use, but there are no 'when not to use' instructions or alternative tool mentions.

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

list_usersB

Get all users. Supports pagination with limit and sorting.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNo
limitNo

TDQS

B3.1/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 pagination and sorting behavior, which adds context beyond the raw schema. However, it omits details like default values, maximum limit, authentication requirements, or response structure, leaving gaps.

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 short sentences, front-loaded with the primary purpose, and contains no redundant or filler content. Every word earns its place.

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

Completeness3/5

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

For a simple list tool with optional pagination parameters, the description is mostly sufficient. However, the lack of an output schema means the return format is unstated, and the phrase 'all users' could mislead without explicitly explaining that pagination limits the result set. Still, the description provides adequate context for basic usage.

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

Parameters2/5

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

The schema has zero description coverage, so the description must explain parameter meanings. It mentions 'limit and sorting' but does not clarify what field sorting applies to or how limit behaves. The enum values asc/desc are self-evident, but the description adds minimal semantic value beyond parameter names.

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 returns all users, which is a specific verb+resource. It is distinguishable from sibling tool get_user (singular) and other entities like products or carts, though it does not explicitly mention the alternative.

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

Usage Guidelines2/5

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

The description provides no explicit guidance on when to use this tool versus alternatives like get_user. It implies use for listing users with pagination, but does not state exclusions or when another tool would be more appropriate.

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. 9 tool updatesv1.0.1
    • First observedget_cart
    • First observedget_product
    • First observedget_products_by_category
    • First observedget_user
    • First observedget_user_carts
    • First observedlist_carts
    • First observedlist_categories
    • First observedlist_products
    • First observedlist_users

TDQS

A3.8/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a distinct resource and action: products, categories, carts, and users each have list/get operations, with get_products_by_category and get_user_carts providing specific filtered views. There is no overlap or ambiguity between tools.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern: list_* for collections and get_* for individual items. The compound names like get_products_by_category and get_user_carts remain readable and fit the same convention.

Tool Count5/5

With 9 tools, the server is well-scoped for a fake store API covering products, categories, carts, and users. Every tool serves a clear purpose without redundancy or bloat.

Completeness4/5

The coverage is complete for read-only browsing: all resources have list and detail retrieval, with category and user-cart filtering. However, there are no create, update, or delete operations, which would be expected for full lifecycle management, but this may be intentional for a fake store demo.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers