Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP GraphQL Sales Server Show me the top 10 customers by total sales"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides access to sales data through GraphQL queries. This server allows AI assistants like Claude to interact with a Northwind-style sales database through natural language queries.
GraphQL API with comprehensive sales data queries
MCP Server compatible with Claude Desktop and other MCP clients
Rich Analytics including customer summaries, product analytics, and order statistics
Date-based Filtering for time-range queries
FastMCP integration for easy tool development
Related MCP server: Shopify MCP Server
Orders - Complete order information with details, shipping, and line items
Customers - Customer information and purchase history
Products - Product catalog with pricing and sales data
Employees - Employee information linked to orders
Get all orders or specific orders by ID
Filter orders by customer (name or ID)
Calculate customer spending totals and order counts
Generate sales summaries for customers and products
Date-range filtering and analytics
Top products by quantity or revenue
Python 3.8 or higher
uv package manager
Claude Desktop (for MCP integration)
git clone https://github.com/JamBelg/MCP-graphql-Claude.git
cd mcp-graphql-sales-server# Create virtual environment and install dependencies
uv venv
uv pip install -r requirements.txtEnsure you have your sales data file at sales/data.json. The data should follow the Northwind database structure with orders containing:
{
"Order Details": {
"Order ID": "10248",
"Order Date": "1996-07-04",
"Total Price": "440.00"
},
"Customer Details": {
"Customer ID": "VINET",
"Customer Name": "Vins et alcools Chevalier"
},
"Products": [
{
"Product": "Queso Cabrales",
"Quantity": 12,
"Unit Price": 14.0,
"Total": 168.0
}
]
}Create a .env file (optional):
GRAPHQL_ENDPOINT=http://127.0.0.1:5001/graphql
LOG_LEVEL=INFOTerminal 1 - GraphQL Server:
python graphql_client/client.pyTerminal 2 - MCP Server:
python main.py# GraphQL Server
uv run graphql_client/client.py
# MCP Server
uv run main.pymacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"sales-graphql": {
"command": "/path/to/.local/bin/uv",
"args": [
"--directory",
"/full/path/to/mcp-graphql-sales-server",
"run",
"main.py"
]
}
}
}Important: Replace /full/path/to/mcp-graphql-sales-server with the actual absolute path to your project directory.
Completely quit and restart Claude Desktop to load the new configuration.
Once integrated with Claude Desktop, you can ask questions like:
"Can you get all orders from the sales database?"
"Show me orders for customer 'ALFKI'"
"What's the total spent by customer 'Antonio Moreno'?"
"Get me the top 10 customers by sales volume"
"Show me order summary statistics"
"Find all orders from July 1996"
"Which products sell the most by quantity?"Check out this interactive visualization showing the top 10 customers by sales and order count: Top 10 Customers Sales Report
This report demonstrates the kind of rich analytics and visualizations you can generate using this MCP server with Claude's data analysis capabilities.
Access the GraphQL playground at: http://127.0.0.1:5001/graphql
# Get comprehensive order statistics
{
orderSummaryStats {
totalOrders
totalRevenue
uniqueCustomers
averageOrderValue
dateRange
}
}
# Get customer sales summary
{
customersSalesSummary(limit: 5, sortBy: TOTAL_SALES) {
customerName
totalSales
orderCount
}
}
# Get specific customer's orders
{
ordersByCustomerName(customerName: "Alfreds Futterkiste") {
orderDetails {
orderId
orderDate
totalPrice
}
products {
product
quantity
unitPrice
total
}
}
}mcp-graphql-sales-server/
├── README.md
├── requirements.txt
├── .env.example
├── main.py # Entry point
├── mcp_server/
│ ├── __init__.py
│ ├── server.py # MCP server setup
│ └── tools/
│ ├── __init__.py
│ └── graphql_tools.py # MCP tools for GraphQL queries
├── graphql_client/
│ ├── __init__.py
│ ├── client.py # GraphQL server & schema
│ └── queries.py # Additional GraphQL utilities
├── config/
│ ├── __init__.py
│ └── settings.py # Configuration management
├── sales/
│ └── data.json # Sales data file
└── tests/
└── test_tools.pyThe server provides these tools for AI interaction:
graphql_query - Execute raw GraphQL queries
test_connection - Test GraphQL endpoint connectivity
get_all_orders - Retrieve all orders with complete details
get_order_by_id - Get specific order by ID
get_orders_by_customer_name - Get customer's orders by name
get_orders_by_customer_id - Get customer's orders by ID
get_total_spent_by_customer - Calculate customer total spending
orders_after_date - Filter orders after specific date
orders_between_dates - Filter orders within date range
get_order_summary - Get comprehensive order statistics
400 Bad Request errors: Ensure GraphQL server is running on port 5001
MCP tools not showing: Check Claude Desktop config path and restart the application
Data file errors: Verify sales/data.json exists and is properly formatted
Permission errors: Ensure all files are readable and paths are correct
Check logs at: /tmp/mcp_sales_server.log
curl -X POST http://127.0.0.1:5001/graphql \
-H "Content-Type: application/json" \
-d '{"query": "{ orders { orderDetails { orderId } } }"}'fastmcp>=0.9.0
requests>=2.31.0
python-dotenv>=1.0.0
flask>=2.3.0
flask-graphql>=2.0.1
graphene>=3.3.0Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Built with FastMCP for easy MCP server development
Uses Graphene for GraphQL schema generation
Inspired by the Northwind database sample data structure
Need help? Open an issue on GitHub or check the troubleshooting section above.
Retrieve all orders with complete details.
Returns:
Dict containing all orders or error information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It does reveal that the operation returns a dictionary containing all orders or error information, which is useful, but it does not explicitly state safety (e.g., read-only nature) or any potential side effects. For a simple retrieval, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: a single clear sentence stating the action, followed by a brief return description. Every word adds value, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects) and the presence of an output schema, the description sufficiently covers behavior. It states the return format (dict of all orders or error info) and does not need to elaborate further. The context signals indicate the output schema exists, so return structure details are already captured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema description coverage is 100% (vacuously). Per the baseline rule for 0 parameters, a score of 4 is appropriate since the description does not need to explain parameters that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve all orders with complete details,' which is a specific verb+resource combination. The phrase 'all orders' distinguishes it from sibling tools like get_order_by_id or get_orders_by_customer_name, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need all orders, but it does not explicitly mention when not to use it or provide alternatives. There is no comparison to sibling tools, so the guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific order by its ID.
Args:
order_id: The order ID to search for
Returns:
Dict containing the order details or error information
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return format ('Dict containing the order details or error information'), which is helpful. However, it does not explicitly state that the operation is read-only, mention permissions, or describe error conditions beyond 'error information', limiting transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured with clear Args and Returns sections. Every sentence earns its place, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 nested objects, output schema present), the description covers purpose, parameter, and return behavior. However, it could be more complete by explicitly guiding usage relative to the many sibling order-related tools, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains order_id as 'The order ID to search for', adding meaning beyond the schema's bare 'Order Id' title. This adequately describes the parameter for a simple lookup, though it lacks examples or format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a specific order by its ID', which is a specific verb+resource+scope. This distinguishes it from sibling tools like get_all_orders and get_orders_by_customer_name, which operate on different criteria or return multiple orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an order ID and need that specific order, but it does not explicitly state when to use it over alternatives. No mention of when not to use or reference to sibling tools, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all orders for a specific customer by ID.
Args:
customer_id: The customer ID to search for
Returns:
Dict containing the customer's orders or error information
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of behavior. It states the return type 'Dict containing the customer's orders or error information' but does not explicitly mention read-only semantics, pagination, or side effects. While it gives some transparency, more detail would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and follows a clear structure with Args and Returns sections. No redundant text is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter, the description covers the core purpose, argument, and return shape. An output schema exists, so return details are presumably available, but the description also mentions 'error information' for completeness. It lacks explicit notes on error behavior or pagination, but these are not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains 'customer_id: The customer ID to search for,' adding meaning to the schema's bare string type. With schema description coverage at 0%, this compensation is necessary and adequately clarifies the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve all orders for a specific customer by ID,' providing a specific verb and resource. It distinguishes from siblings like get_order_by_id by indicating 'all orders' for a customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a customer ID is available and all orders are needed, but it does not explicitly mention alternatives or when not to use this tool. No exclusions are provided, making the guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all orders for a specific customer by name.
Args:
customer_name: The customer name to search for
Returns:
Dict containing the customer's orders or error information
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose that the return is a dict and may contain error information, but it does not mention specifics like exact matching behavior, duplicate customer names, or authentication requirements. Some behavioral details are present, but key operational nuances remain undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with an opening sentence followed by Args and Returns sections. It contains no filler and is easy to parse, though the Args section is redundant with the schema but necessary due to schema lacking descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers the core behavior and parameter, but it omits usage alternatives and edge cases (e.g., multiple customers with the same name). It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description's Args section provides the only meaning for the parameter: 'customer_name: The customer name to search for'. This is a basic definition but does not add depth like case sensitivity, full vs. partial name, or formatting requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve all orders') and the scope ('for a specific customer by name'), using a specific verb and resource. It distinguishes itself from sibling tools like get_orders_by_customer_id (by ID) and get_all_orders (all customers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool should be used when a customer name is available, but it does not explicitly mention alternatives or exclusion criteria. Sibling tools like get_orders_by_customer_id are not referenced, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of all orders including counts and totals.
Returns:
Dict containing order summary statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It mentions the return type (Dict with summary stats), but does not explicitly state that this is a read-only operation, whether any side effects exist, or if special permissions are required. The verb 'get' hints at safety but does not fully disclose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose and a returns note. No filler words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is a simple 0-param tool with an output schema, the description covers the essential purpose. It could explicitly contrast with get_all_orders for richer context, but the current information is sufficient for a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter info, which is fine since there are no parameters to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a summary of all orders including counts and totals' - a specific verb, resource, and scope. This clearly distinguishes it from siblings like get_all_orders which likely returns individual orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for aggregated summary rather than detailed order lists, but it does not explicitly say when to use this tool versus get_all_orders or other alternatives. No when-not-to-use or exclusion guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the total amount spent by a customer.
Args:
customer_name: The customer name to calculate total spending for
Returns:
Dict containing the total spent or error information
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the return is a dict containing total spent or error information, which gives some transparency. However, it does not explicitly state that the operation is read-only, how errors are represented, or whether customer_name requires exact match.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with Args/Returns sections. Every sentence earns its place, and there is no redundant fluff beyond the slightly repetitive parameter explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter) and the presence of an output schema, the description is adequate for basic invocation. However, it lacks usage context relative to sibling tools, making it less complete for an agent deciding between options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no property descriptions (coverage 0%), so the description must compensate. Yet it only repeats the parameter name ('customer_name') with a near-identical phrase, adding no extra meaning about format, case sensitivity, or examples. Minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the total amount spent') and the resource (a customer). It distinguishes itself from sibling tools like 'get_orders_by_customer_name' or 'get_order_summary' by focusing specifically on total spend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of required input format, exact matching, or scenarios such as 'use this for aggregated spending' versus other order-level tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a raw GraphQL query against the sales API.
Args:
query: The GraphQL query string
variables: Optional variables for the query
Returns:
Dict containing the GraphQL response or error information
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| variables | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It states it returns a dict with response or error information, but does not clarify whether this can execute mutations, require special permissions, or have rate limits. The term 'raw' hints at power but does not explicitly disclose risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose followed by Args and Returns sections. Every line adds value without redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose, arguments, and return type, and the presence of an output schema reduces the need to detail return values. However, it lacks guidance on when to use this raw tool versus siblings and does not mention potential side effects or use cases, leaving gaps for an AI agent deciding how to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for parameters, so the description's Args section adds meaning by specifying that query is the GraphQL query string and variables are optional. This is helpful, though it does not provide examples or constraints beyond optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a raw GraphQL query against the sales API, using a specific verb and resource. The word 'raw' distinguishes it from the specialized sibling tools like get_order_by_id, indicating it is a low-level, flexible query mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus the specialized sibling tools. The description mentions it is a 'raw' query but does not state when it should be preferred (e.g., for custom queries not covered by get_* functions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all orders after a given date (YYYY-MM-DD).
Note: This filters locally since the GraphQL schema doesn't have date filters.
Args:
date: Date string in YYYY-MM-DD format
Returns:
Dict containing filtered orders or error information
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of disclosing behavior. It explicitly states that filtering is done locally (a key implementation detail) and that the return is a dict containing filtered orders or error information. This adds meaningful behavior beyond what a static schema would reveal, though it could mention performance implications of fetching all orders first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured. It opens with the core purpose, includes a brief note on filtering behavior, and then clearly lists arguments and returns. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers the input format, return type, and filtering behavior. It could specify whether 'after' includes the given date, but this is a minor gap and not essential for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'date' as a string with no description. The tool's description adds critical format information (YYYY-MM-DD) in the Args section, which is essential for correct invocation. This compensates well for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve all orders after a given date (YYYY-MM-DD)' with a specific verb, resource, and scope. It distinguishes itself from siblings like orders_between_dates (range) and get_all_orders (no filter) by emphasizing the date-based filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The note 'This filters locally since the GraphQL schema doesn't have date filters' provides helpful context on why this tool exists and when to use it. However, it does not explicitly mention alternatives like orders_between_dates for range queries or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all orders between two dates (inclusive).
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
Returns:
Dict containing filtered orders or error information
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| start_date | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It mentions 'inclusive' boundaries and describes the return value as a dict with filtered orders or error information, which provides useful behavioral context. However, it does not disclose potential pitfalls like date validation 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-structured docstring with Args and Returns sections. It is concise, with no fluff, and every sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, parameters, and return value, and there is an output schema. It lacks mention of edge cases like start_date > end_date, but remains fairly complete for a basic retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description compensates by explicitly stating the YYYY-MM-DD format for both start_date and end_date. It adds required meaning beyond the schema's simple titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all orders between two dates (inclusive). This is a specific verb and resource, and it is distinct from sibling tools like orders_after_date or get_all_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for date-range queries but does not explicitly differentiate from orders_after_date or other sibling tools. It lacks exclusions or alternative recommendations, so the agent may not know when to choose this over similar date-based tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test the connection to the GraphQL endpoint.
Returns:
Dict containing connection status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states that it tests a connection and returns a status dict, but doesn't mention whether it's read-only, performs a network call, or what failure behavior looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two short sentences, with the main purpose front-loaded. There is no redundant information, making it efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description adequately covers purpose and return type. The presence of an output schema fills in return details. However, a brief note on when to use it (e.g., as a health check) would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (no parameters), so the description is not required to explain parameters. The baseline for zero parameters is 4, and no additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Test') with a clear resource ('connection to the GraphQL endpoint') and states the return type (Dict with connection status). This clearly distinguishes it from sibling tools that query order data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives. There is no mention of use cases, exclusions, or prerequisites, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_all_ordersget_order_by_idget_order_summaryget_orders_by_customer_idget_orders_by_customer_nameget_total_spent_by_customergraphql_queryorders_after_dateorders_between_datestest_connectionScored across 10 tools
Each tool targets a distinct query pattern: order by ID, all orders, by customer name/ID, date ranges, summary, and raw GraphQL. get_orders_by_customer_name and get_orders_by_customer_id are similar but clearly differentiated by the lookup key. graphql_query could overlap with any tool but is explicitly raw and optional.
Most tools follow a get_* pattern (get_order_by_id, get_all_orders, get_total_spent_by_customer), but graphql_query, test_connection, and the date-based tools (orders_after_date, orders_between_dates) deviate slightly. The naming is still intuitive and readable.
10 tools is a well-scoped size for a sales query server. Each tool provides a distinct, useful capability without unnecessary redundancy, and the count fits comfortably within the ideal range for a focused server.
The server covers a comprehensive set of order-read operations: retrieval by ID, all, customer name/ID, date filtering, total spend, and summary statistics. A raw GraphQL query tool fills in gaps. Missing write operations and customer resource tools, but for a read-focused sales query server this is substantial.
Ask questions in plain language, get answers from your business database. No SQL required.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
Run SOQL queries to explore and retrieve Salesforce data. Access accounts, contacts, opportunities…
