Skip to main content
Glama

BILLZ MCP Server

MCP server for the BILLZ POS/Retail API 2.0.

Modes

Mode

Tools

Description

analytics (default)

18

Read-only analytics & lookup — safe for AI agents

full

80+

All tools including write operations (sales, write-offs, transfers, etc.)

Set via BILLZ_MCP_MODE environment variable.

Related MCP server: MCP Business AI Transformation

Setup

1. Build

cd billz_mcp
npm install
npm run build

2. Get your API key

In BILLZ Admin → Settings → Integrations → create an API key. Grant the key read access to Products, Sales, Reports, etc. (permission matrix in BILLZ Admin).

2b. Verify read APIs (optional)

Calls the same HTTP paths as BILLZ_MCP_MODE=analytics (18 read tools). Use the same secret you pass to MCP:

cd billz_mcp
npm install
BILLZ_SECRET_KEY='your_key' npm run smoke:read

You can also put BILLZ_SECRET_KEY=... in billz_mcp/.env. Exit code 0 means every check passed.

3. Add to Cursor (or any MCP client)

{
  "mcpServers": {
    "billz": {
      "command": "node",
      "args": ["/absolute/path/to/billz_mcp/dist/index.js"],
      "env": {
        "BILLZ_SECRET_KEY": "your_secret_key_here",
        "BILLZ_MCP_MODE": "analytics"
      }
    }
  }
}

Environment Variables

Variable

Required

Default

Description

BILLZ_SECRET_KEY

Yes

API integration key from BILLZ Admin

BILLZ_MCP_MODE

No

analytics

analytics (18 tools) or full (80+)

BILLZ_PLATFORM_ID

No

built-in

Platform ID header value

Analytics Mode (default) — 18 tools

Products (2)

Tool

Description

billz_get_products

List products (delta sync via last_updated_date)

billz_filter_products

Advanced product search with filters

Sales (3)

Tool

Description

billz_get_sales

List completed sales

billz_get_sale_details

Single sale deep dive

billz_search_sales

Advanced sales search (v3)

Customers (3)

Tool

Description

billz_get_customers

List/search customers

billz_get_customer

Single customer detail

billz_get_debt_stats

Debt overview

Reports (6)

Tool

Description

billz_report_general_table

KPI dashboard (sales, products, customers)

billz_report_general_totals

KPI totals/sums

billz_report_products_table

Sales by product

billz_report_customers_table

Customer analytics

billz_report_profit_loss

Profit & loss

billz_report_stock

Inventory levels by date

Reference Data (4)

Tool

Description

billz_get_shops

Shop list

billz_get_categories

Product categories

billz_get_brands

Product brands

billz_get_product_characteristics

Custom field definitions

Full Mode — additional tools

Set BILLZ_MCP_MODE=full to unlock all 80+ tools including:

  • Products: create, patch custom fields

  • Sales: create draft, add products, apply discount, attach customer, complete, postpone, manage drafts

  • Customers: create, update, set balance, loyalty cards

  • Supplier Orders: create, add products, update, send

  • Transfers: create, add products, send, cancel, accept, update

  • Imports: bulk import products

  • Promotions: list promos, details, promo products

  • Write-offs: create, add products, cancel, complete, reasons

  • Stocktaking: list sessions

  • Certificates/Gift Cards: search, create, add/remove from sale, pay

  • Reports: 19 additional report tools (transactions, performance, imports, suppliers, etc.)

  • Auxiliary: company, users, suppliers, measurement units, cashboxes, payment types, currencies

MCP Resources

API documentation is exposed as MCP resources via billz://docs/{key} (available in both modes).

Project Structure

src/
  index.ts              Server init, mode gating, module registration
  billz-client.ts       HTTP client with JWT auth & 401 retry
  helpers.ts            Shared ok() helper, McpMode type
  resources.ts          MCP resources (API docs)
  tools/
    products.ts         2 analytics + 3 full
    customers.ts        3 analytics + 7 full
    sales.ts            3 analytics + 12 full
    reports.ts          6 analytics + 19 full
    auxiliary.ts        4 analytics + 10 full
    orders.ts           6 full-only
    transfers.ts        8 full-only
    imports.ts          2 full-only
    promotions.ts       3 full-only
    writeoffs.ts        5 full-only
    stocktaking.ts      1 full-only
    certificates.ts     5 full-only

Available Tools

9 tools
billz_get_brandsC

Get list of product brands

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
limitNo
searchNo

TDQS

C2.1/5.0
Behavior1/5

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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It fails to mention pagination behavior, sorting, authentication requirements, rate limits, or any side effects. The description is minimal and leaves the agent guessing about the tool's behavior.

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

Conciseness2/5

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

The description is extremely concise at one sentence, but this brevity comes at the cost of essential details. It is under-specified for a tool with three parameters and no annotations. Conciseness should not sacrifice completeness.

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

Completeness1/5

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

Given the tool has three optional parameters, no output schema, and no annotations, the description is grossly inadequate. It provides no context for filtering, pagination, or expected result format. The agent cannot reliably use this tool based solely on the description.

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

Parameters1/5

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

Schema description coverage is 0%, so the description should compensate by explaining parameter purpose. It does not mention page, limit, or search. The description adds no value beyond the schema structure, leaving the agent without guidance on parameter usage.

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 'Get list of product brands' clearly states the verb and resource. It distinguishes from sibling tools like billz_get_categories and billz_get_shops, as brands are a distinct entity. However, it lacks any additional context about what constitutes a brand.

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 is provided on when to use this tool versus alternatives. There are no exclusions or context signals to help the agent decide. The description does not mention typical use cases or prerequisites.

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

billz_get_categoriesC

Get product categories

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
limitNo
searchNo
is_deletedNo

TDQS

C2/5.0
Behavior2/5

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

No annotations provided, so description must disclose behavior. It only implies read-only with 'Get', but does not confirm or describe any side effects, pagination, or filtering behavior.

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

Conciseness2/5

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

Extremely short at 3 words, but this is under-specification, not conciseness. For a tool with 4 optional parameters and no annotations, the description should include more details.

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

Completeness1/5

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

Given 4 parameters, no output schema, and no annotations, the description is grossly inadequate. The agent lacks necessary information to invoke the tool correctly.

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

Parameters1/5

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

The input schema has 4 parameters (page, limit, search, is_deleted) with 0% description coverage. The description does not mention any parameter meaning, leaving the agent without guidance on how to use them.

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

Purpose3/5

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

Description says 'Get product categories', which is a clear verb+resource. However, it does not distinguish from sibling tools like billz_get_brands, which similarly retrieve lists. More specificity would help.

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 over alternatives. The description lacks context about scenarios or exclusions.

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

billz_get_product_characteristicsC

Get product custom field definitions

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

TDQS

C2.4/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. While 'get' implies a read operation, it does not explicitly state that the tool is read-only or disclose any other behavioral traits such as authorization requirements or performance considerations.

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 very short (one sentence), but it lacks necessary details that should be included. It is concise but not complete, so a score of 4 reflects that it is not verbose but still under-informative.

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?

For a simple tool with one optional parameter and no output schema, the description should at least explain what 'product custom field definitions' are and how the 'limit' parameter works. It fails to provide this context, leaving the agent without enough information for correct invocation.

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

Parameters1/5

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

The only parameter 'limit' has no description in the schema, and the tool description does not explain its purpose or effect. With 0% schema description coverage, the description fails to compensate.

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 states the specific verb 'get' and resource 'product custom field definitions', which clearly indicates what the tool does. However, it does not differentiate from sibling tools like billz_get_shops which also use 'get', but the resource name is distinct enough.

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

Usage Guidelines1/5

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 context, prerequisites, or exclusions.

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

billz_get_sale_detailsC

Get details of a specific sale

ParametersJSON Schema
NameRequiredDescriptionDefault
order_idYes

TDQS

C2.4/5.0
Behavior2/5

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

No annotations exist, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or rate limits. The action 'Get' implies a read operation, but this is not explicitly stated.

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

Conciseness3/5

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

The description is a single sentence, which is concise, but it is too brief to be informative. It lacks structure and detail.

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?

Given the tool has one parameter and no output schema, the description is insufficient. It does not explain what 'details' are returned, leaving ambiguity.

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

Parameters1/5

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

The description adds no meaning beyond the input schema. The sole parameter order_id is not described at all, and schema description coverage is 0%. The description should explain what order_id represents.

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 specifies the verb 'Get' and the resource 'details of a specific sale', making the action clear. However, it does not differentiate from sibling tools like billz_search_sales, which might also return sale details.

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 (e.g., billz_search_sales). No prerequisites or context provided.

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

billz_get_shopsC

Get list of shops

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
only_allowedNo

TDQS

C2.4/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does not mention whether the list is paginated, if it requires authentication, or what the 'only_allowed' parameter implies behaviorally.

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

Conciseness3/5

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

The description is very concise (one sentence), but this conciseness sacrifices utility. It is front-loaded but lacks necessary details, making it under-specified.

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?

Given the tool has 2 optional parameters, no output schema, and no annotations, the description is incomplete. It does not cover return format, pagination, or the effect of parameters, leaving significant gaps for an agent to understand the tool's behavior.

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?

Schema description coverage is 0%, and the description does not explain the parameters 'limit' or 'only_allowed'. While the names hint at their meaning, no explicit semantics or constraints are given, which is insufficient for proper agent usage.

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

Purpose3/5

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

The description 'Get list of shops' uses a verb+resource structure, but it is generic and does not differentiate from sibling tools like billz_get_categories or billz_get_brands. It lacks specifics on what kind of shops are returned (e.g., all shops, user-specific, etc.).

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 billz_search_sales or billz_get_categories. No context on prerequisites or typical use cases is provided.

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

billz_report_customers_tableC

Customer statistics report table

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
limitNo
currencyNo
end_dateNo
shop_idsNo
start_dateYes

TDQS

C2/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits such as that the tool retrieves data, requires a date range, or supports pagination. The agent learns nothing about side effects or constraints.

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

Conciseness2/5

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

At only 4 words, the description is too short to convey necessary information. This is under-specification, not conciseness; it fails to earn its space.

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

Completeness1/5

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

Given 6 parameters, no output schema, and several sibling tools, the description is completely inadequate. It omits essential context for correct invocation, such as the report's content, filtering options, and how results are structured.

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

Parameters1/5

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

With 0% schema description coverage and no parameter explanations in the description, the agent receives no help understanding the meaning of parameters like 'shop_ids', 'currency', or 'limit'. The description adds no semantic value.

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

Purpose3/5

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

The description 'Customer statistics report table' indicates a report on customer statistics but lacks a verb and specific details. It vaguely suggests the tool produces a table of customer data, but does not clearly state what statistics are included, making it somewhat ambiguous.

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 compared to sibling report tools like billz_report_general_totals or billz_report_profit_loss. An agent has no context to decide between them.

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

billz_report_general_totalsD

General summary report totals (sums)

ParametersJSON Schema
NameRequiredDescriptionDefault
currencyNo
end_dateNo
shop_idsNo
start_dateYes

TDQS

D1.9/5.0
Behavior2/5

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

No annotations exist, so the description must fully disclose behavior. It only mentions 'totals (sums)' but does not indicate whether the operation is read-only, whether it aggregates across time or shops, or what permissions are needed.

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

Conciseness2/5

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

The description is extremely short (5 words) but lacks substance. Conciseness is not useful when it omits critical information needed for correct invocation.

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

Completeness1/5

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

With no output schema, no annotations, and four parameters, the description is severely inadequate. It does not explain return values, default behaviors, or how parameters interact, leaving an agent unable to use the tool effectively.

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?

Schema description coverage is 0%, and the description adds no information about parameters. While parameter names like start_date and shop_ids are somewhat self-explanatory, format details, constraints, or examples are missing.

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

Purpose2/5

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

The description 'General summary report totals (sums)' is vague about what the report actually contains. It does not specify what data is being totaled (e.g., sales, customers, inventory) and fails to differentiate from sibling tools like billz_report_profit_loss or billz_report_customers_table.

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 is provided on when to use this tool versus other report tools. There are no mentions of alternatives, prerequisites, or typical use cases.

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

billz_report_profit_lossD

Profit and loss report

ParametersJSON Schema
NameRequiredDescriptionDefault
currencyNo
end_dateNo
shop_idsNo
start_dateYes

TDQS

D1.8/5.0
Behavior1/5

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

With no annotations, the description must disclose behavioral traits. It does not mention that the tool is read-only, whether authentication is needed, or what the report includes. The description is silent on all behavioral details.

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

Conciseness2/5

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

The description is extremely short (one phrase), but it sacrifices informativeness for brevity. A few more sentences would improve clarity without becoming verbose.

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

Completeness1/5

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

Given the tool has four parameters, no output schema, and no annotations, the description is wholly inadequate. It fails to provide essential context like parameter syntax, required fields, or report scope.

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

Parameters1/5

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

Schema coverage is 0%, and the description does not explain any of the four parameters (start_date, end_date, currency, shop_ids). It adds no meaning beyond the schema field names.

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

Purpose3/5

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

The description 'Profit and loss report' identifies the tool's purpose as generating a profit and loss report, which distinguishes it from sibling reports like general totals or customers table. However, it lacks a verb and specific resource details, making it only marginally clear.

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 is provided on when to use this report versus alternatives such as billz_report_general_totals. The description offers no context or prerequisities.

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

billz_search_salesC

Search sales with advanced filters (v3 endpoint)

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
limitNo
searchNoSearch by order number, customer name, phone
statusNoe.g. completed, draft, postponed
end_dateNo
shop_idsNoComma-separated shop UUIDs
seller_idsNoComma-separated seller UUIDs
start_dateNo
cashier_idsNoComma-separated cashier UUIDs

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only states 'Search sales with advanced filters (v3 endpoint)', failing to mention pagination defaults, rate limits, or that the endpoint is read-only. The schema includes page/limit but the description adds no 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.

Conciseness4/5

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

The description is a single, short sentence that is concise and front-loaded with the core action. It is not verbose, but could include additional high-level details without losing 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?

Given 9 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not mention return format, pagination behavior, or date range implications. The schema partially compensates but the description fails to provide overarching context.

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 56% description coverage (5 of 9 parameters documented). The tool description does not add new parameter meaning beyond 'advanced filters'. Since coverage is moderate, a baseline of 3 is appropriate; the description does not compensate for undocumented parameters.

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 verb 'Search' and the resource 'sales', indicating a listing/filtering function. The phrase 'advanced filters' hints at multiple parameters, which is accurate given the schema. However, it does not explicitly differentiate from sibling tools like billz_get_sale_details, which could be misconstrued as similar.

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 is provided on when to use this tool versus alternatives. For example, it does not explain that this tool is for broad searches with filters, while billz_get_sale_details might be for retrieving a single sale by ID. The description lacks exclusions or contexts.

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.2.0
    • First observedbillz_get_brands
    • First observedbillz_get_categories
    • First observedbillz_get_product_characteristics
    • First observedbillz_get_sale_details
    • First observedbillz_get_shops
    • First observedbillz_report_customers_table
    • First observedbillz_report_general_totals
    • First observedbillz_report_profit_loss
    • First observedbillz_search_sales

TDQS

C2.6/5.0

Scored across 9 tools

Disambiguation4/5

Most tools target clearly distinct resources: product characteristics, sale details, sales search, reports, shops, categories, and brands. The main source of potential confusion is between billz_report_general_totals and billz_report_profit_loss, which both deal with aggregated financial figures, though their descriptions separate them reasonably.

Naming Consistency4/5

Tool names follow a mostly consistent pattern of billz_ + action + resource: get_product_characteristics, get_sale_details, get_shops, get_categories, get_brands, search_sales, report_general_totals, report_customers_table, report_profit_loss. The minor inconsistency is the report_* prefix vs get_*/search_*, and report_customers_table is slightly awkward, but overall the pattern is readable and predictable.

Tool Count5/5

Nine tools is well within the ideal range for an integration server. Each tool covers a distinct area of the Billz retail/ERP domain without feeling padded or redundant.

Completeness3/5

The server covers sales retrieval, reporting, and reference data like shops, categories, and brands. However, it lacks basic product catalog access (only product characteristics are available), and there is no way to list or fetch individual customers, even though customer reports exist. This leaves notable gaps in the apparent domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    C
    maintenance
    Enterprise-grade MCP server with multi-agent system for business AI transformation across finance, healthcare, retail, and other domains. Provides specialized AI agents for data analysis, API execution, business validation, and report generation with real-time monitoring and observability.
    -
  • F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI agents to manage multi-marketplace e-commerce operations by connecting to the SellerChamp API. It supports inventory reporting, cross-listing analysis, order management, and bulk updates across platforms like Amazon, eBay, and Shopify.
    -