Skip to main content
Glama
voucherifyio

voucherify-core-mcp

Official
by voucherifyio
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Voucherify Core MCP

Use a MCP (Model Context Protocol) server to ask questions in plain language and explore your loyalty and promo data through Voucherify API endpoints. An MCP works like a teammate to pull the numbers for you.

Read complete Voucherify Core MCP article

Related MCP server: SE Ranking SEO Data API MCP Server

Pick your path

Set up MPC connection in two ways:

  • Use the published package (recommended): no local build; your agent spawns the server

  • Contribute or run from source: set up the repo, run locally (HTTP or stdio), and hack away 🚀

Use the published package (recommended)

You don't need a local setup. Your agent runs the server with uvx.

Package prerequisites

To set up Voucherify Core MCP, you need:

  • An MCP client (for example Cursor, Claude Desktop, Visual Studio Code)

  • UV installed (remember to restart your client if you've installed UV for the first time)

  • Recommended: Use a separate Voucherify server-side app ID and token for the MCP.

Set up Voucherify Core MCP

To set up Voucherify Core MCP:

  1. Open your MCP client.

  2. Add the following code snippet to the mcp.json file in your client. This step may vary depending on your client; refer to the specific documentation for details.

    {
  "version": 1,
  "mcpServers": {
    "voucherify-core-mcp": {
      "command": "uvx",
      "args": ["voucherify-core-mcp", "--transport", "stdio"],
      "env": {
        "VOUCHERIFY_APP_ID": "<app id>",
        "VOUCHERIFY_APP_TOKEN": "<app token>",
        "VOUCHERIFY_API_BASE_URL": "https://<clusterId>.api.voucherify.io"
      }
    }
  }
}

  3. Copy your Voucherify server-side app ID and token from Project settings into the mcp.json.

  4. Provide your Voucherify API base URL. For shared clusters:

    • Europe: https://api.voucherify.io

    • North America: https://us1.api.voucherify.io

    • Asia: https://as1.api.voucherify.io

  5. Run the connection with the MCP server.

  6. Open a new chat to start your conversation.

Contribute or run from source

If you want to explore the code, tweak things, or run a local HTTP server, follow this setup.

Contribute: Prerequisites

  • Python 3.12+

  • Voucherify credentials: VOUCHERIFY_APP_ID, VOUCHERIFY_APP_TOKEN (use a separate pair)

  • UV installed (remember to restart your client if you've installed UV for the first time)

  • Installed dependencies:

uv sync --all-extras

Configure project credentials

Create an .env file in the project root (useful for debugging):

## Voucherify API Configuration for localhost
VOUCHERIFY_API_BASE_URL=http://localhost:8000
VOUCHERIFY_APP_ID=<app id>
VOUCHERIFY_APP_TOKEN=<app token>

## Tests (Management API keys can be found in Team Settings if you have this feature enabled)
VOUCHERIFY_MANAGEMENT_APP_ID=
VOUCHERIFY_MANAGEMENT_APP_TOKEN=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

When running a local MCP server, you can point to a specific cluster or local environment with .env:

VOUCHERIFY_API_BASE_URL=http://localhost:8000

Run it your way

You can run it by:

  • HTTP server

  • stdio

HTTP server

  1. Start the server:

uv run python src/voucherify_core_mcp/main.py

  1. You’ll get an endpoint at http://127.0.0.1:10000/mcp/.

  2. Configure your agent to connect over HTTP:

{
  "mcpServers": {
    "voucherify-remote-mcp": {
      "url": "http://localhost:10000/mcp/",
      "headers": {
        "x-app-id": "your-application-id",
        "x-app-token": "your-secret-key"
      }
    }
  }
}
stdio (spawned by your agent)

Let your agent spawn the server from source:

{
  "version": 1,
  "mcpServers": {
    "voucherify-core-mcp-from-sources": {
      "command": "uv",
      "args": ["run", "python", "src/voucherify_core_mcp/main.py", "--transport", "stdio"],
      "env": {
        "VOUCHERIFY_APP_ID": "<app id>",
        "VOUCHERIFY_APP_TOKEN": "<app token>",
        "VOUCHERIFY_API_BASE_URL": "https://api.voucherify.io"
      }
    }
  }
}

Place the file where your agent expects it (same locations as above).

MCP test engine

Use the test engine to check MCP capabilities in a safe environment.

  1. Initialize project data:

    1. Create your .env as above.

    2. Run the project preparation script:

uv run prepare_project.py

This will: - Look into tests/.test.env and delete the test project defined there. - Create a new test project using the Management API credentials from .env. - Generate required resources. - Persist credentials and resource IDs for tests in .test.env.

  1. Run scenarios

uv run pytest tests/scenario_1_basic_scenarios.py

or a specific test:

uv run pytest tests/scenario_5_get_best_deals.py::test_get_best_deals_json_output

Available functionalities

You can access the following endpoints with the Voucherify MCP to fetch data:

  • Find_customer: Displays a customer's current status and detailed information such as collected loyalty points, eligibility for rewards, and other profile data. You can use the customer's email, source ID, or Voucherify ID.

  • List_campaigns: Retrieves a list of campaigns to view active, scheduled, or completed campaigns.

  • Get_campaign_summary: Displays a performance summary of ongoing campaigns, including comparisons with past activity (for example, previous week), to visualize trends and measure success over time.

  • Get_promotion_tier: Fetches details about the configuration of a promotion tier, such as reward levels or thresholds that determine customer benefits.

  • Qualifications: Checks and returns a customer's eligibility for specific campaigns, promotions, or reward rules, ensuring only qualified users receive incentives.

  • Get_best_deals: Returns information about better prices contextually by showing the top 5 best incentives.

    For the best results, set the Application rule to Partial in Voucherify dashboard, Redemptions section, Stacking rules tab. Read the Stacking rules article for more details.

  • Estimate_loyalty_points: Returns an estimation of how many points a customer will earn for an order

  • List_products: Retrieves the catalog of products, including attributes like pricing, availability, and categories.

  • Get_voucher: Returns full details of a specific voucher, such as code, status, balance, and expiration date, to support redemption or troubleshooting.

Best practices

Follow these practices to get the best results.

Ask specific questions

  • Use precise date ranges (for example “July 2025 redemptions”) instead of vague prompts like “recent redemptions”.

  • Describe exactly what you need: specific campaign names, product categories, or data types.

  • Broad requests (for example “all campaigns in the last 3 years”) usually lead to unclear results.

Add more context if necessary

If results look off, reframe your query or try again. If the AI loops or repeats itself, redirect with a new question or start a new chat with a more detailed prompt.

Ask more questions

Once you've got an answer you like, ask the client to:

  • Suggest additional insights or next steps.

  • Explain how it reached its conclusions to help refine your future prompts.

Change model

If you're not satisfied with answers or the overall process, use a different AI model. Each model is trained on different data, has their own strengths, and is best suited for various tasks.

Prompt examples

Read the following prompt examples for inspiration on how to use Voucherify Core MCP:

  • Find customer by email tom@example.com (or source_id, or customer_id). Return the ID, loyalty_balance, active_vouchers.

  • Count total of customers in segment “VIP”. List their basic details: name, email address, source_id. Turn the data into a CSV-friendly format.

  • List active campaigns with fields: ID, name, type, start_date, end_date.

  • Get voucher by code “BK-4829” and show: status, redemption.count, redemption.limit, balance (for gift or loyalty cards).

  • Get campaign “BK-Sept-20OFF” data: total budget, spent budget, redemption counts, and per-customer caps.

  • Show the campaign with the most coupons generated. Return redemption data for this campaign.

  • Show me the best performing campaign in terms of number of successful redemptions. Return the budget - the total discount value that was applied.

  • Get redemptions aggregated by day between 2025-09-01 and 2025-09-03 (timezone Europe/Warsaw).

  • Get best deals for a customer with this email address. They have these items in their cart: Voucherify T-shirt (SKU: VCH-TST-001, quantity: 1, price: 25 USD), Voucherify Mug (SKU: VCH-MUG-002, quantity: 2, price: 15 USD each). Suggest if there's anything they can do to get even better deals.

The number of API calls made by the Voucherify MCP depends on your question. Complex queries, like get best deals for a given customer, will need more API calls, while simple questions can be limited to just a few or even one, like get campaign summary. The MCP client will ask for confirmation to make an API call.

The API calls made with the Voucherify MCP are included in your billing period.

Troubleshooting and feedback

The Voucherify MCP is still under development and we'd love to have your feedback to improve it. Also, if you've encountered any issues, please let us know. Contact Voucherify support or your account manager.

Disclaimer

The Model Context Protocol (MCP) is a new open-source standard and may still carry potential vulnerabilities. The Voucherify MCP server setup and instructions are provided “as is,” without warranties, and use is at your own risk.

Voucherify is not liable for issues caused by incorrect setup, misuse, or security gaps related to MCP.

If you have questions or need support, please reach out to our team, we’re here to help.

Available Tools

10 tools
estimate_loyalty_pointsA

Estimate how many loyalty points a customer will earn for a given order.

CRITICAL: customer and order are ALWAYS required, even when loyalty_card is provided. The loyalty_card only identifies the campaign — it does NOT replace customer or order.

Calculates the estimated number of points a customer will receive in a loyalty campaign based on the campaign's earning rules and the provided order.

Important Limitations:

  • Returns an estimation, not a precise point value

  • Works only for "Order paid" earning rules

  • For campaigns with tiers, mappings, and multiple earning rules, the actual points may differ as the customer may change tiers during final calculation

Use Case: Show loyalty point banners in checkout flows

  • Display estimated points before order placement

  • Motivate customers by showing point rewards for their current cart

  • Combine with get_best_deals for comprehensive loyalty estimations

Campaign Identification (at least one required):

  • loyalty_card: Loyalty card code or voucher ID — resolves the campaign ID only.

  • campaign_id: Direct loyalty campaign ID — use when already known.

  • Both can be provided: the tool verifies the loyalty card belongs to the given campaign.

Parameters:

  • customer: REQUIRED - Customer identification (id or source_id required). Always provide.

  • order: REQUIRED - Order details with source_id for existing orders or amount for estimation. Always provide.

  • loyalty_card: Loyalty card code or voucher ID (at least one of loyalty_card/campaign_id required)

  • campaign_id: Loyalty campaign ID with 'camp_' prefix (at least one of loyalty_card/campaign_id required)

Customer Object Structure: Required (one of):

  • id: Customer ID with 'cust_' prefix (e.g., "cust_abc123")

  • source_id: External customer identifier Optional:

  • metadata: Dict of custom customer attributes

Order Object Structure: Required (one of):

  • source_id: Existing order ID assigned by Voucherify (e.g., "ord_34567890")

  • amount: Total order amount in cents (e.g., 5000 for $50.00) Optional:

  • metadata: Dict of custom order attributes

Pricing Rules:

  • All amounts in cents (5000 = $50.00, 150 = $1.50)

Examples:

  • estimate_loyalty_points( loyalty_card="Loyalty-ZC4Vg", customer={"source_id": "customer123"}, order={"amount": 5000} )

  • estimate_loyalty_points( campaign_id="camp_XXXXXXXXX", customer={"id": "cust_abc123"}, order={"source_id": "ord_34567890"} )

  • estimate_loyalty_points( loyalty_card="Loyalty-ZC4Vg", campaign_id="camp_XXXXXXXXX", customer={"source_id": "customer123"}, order={"amount": 8000, "metadata": {"source": "checkout"}} )

Returns: JSON object containing:

  • campaign: Campaign details (id, name, object)

  • points_estimation: Estimated number of points the customer will earn

Example Response: { "campaign": { "id": "camp_XXXXXXXXX", "name": "Loyalty-campaign", "object": "campaign" }, "points_estimation": 51 }

Error Cases:

  • 400: Campaign doesn't allow auto-join for non-members, inactive campaign, inactive loyalty card, or missing customer/order objects

  • 404: Campaign ID or loyalty card not found

Raises:

  • ToolError: If parameters invalid, campaign not found, or customer not eligible

ParametersJSON Schema
NameRequiredDescriptionDefault
orderYes
customerYes
campaign_idNo
loyalty_cardNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

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

The description fully discloses behavioral traits: it returns an estimation, not precise; only works for 'Order paid' earning rules; limitations about tiers; error cases (400, 404). No annotations are present, so the description carries the full burden and does so thoroughly.

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 well-structured with sections (Critical, Limitations, Use Case, Parameters, Examples, Returns, Errors), front-loaded with purpose and critical notes. Every sentence adds value, and the length is appropriate for the complexity.

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

Completeness5/5

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

The description covers all necessary context: purpose, limitations, parameter details, examples, error cases, and response format. Despite having an output schema, the description enhances understanding. No gaps remain for an agent to use the tool correctly.

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

Parameters5/5

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

Schema description coverage is 0%, but the description explains all parameters in detail, including object structures, required fields, examples, and the relationship between loyalty_card and campaign_id. It fully compensates for the lack of schema descriptions.

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

Purpose5/5

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

The description clearly states the tool estimates loyalty points for a given order, distinguishing from siblings by mentioning 'Combine with get_best_deals for comprehensive loyalty estimations.'

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

Usage Guidelines5/5

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

Explicit use cases (checkout flows, before order placement) and limitations (estimation only, works only for 'Order paid' earning rules) are provided, along with when not to use and alternative tool suggestions.

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

find_customerA

Find a customer by email or ID and return complete customer object.

Lookup Behavior:

  • ID lookup: Direct retrieval by customer ID (faster, more reliable)

  • Email lookup: Searches customers and returns first match (case-insensitive)

  • Returns complete customer object including loyalty summary when available

Parameters:

  • email: Valid email address for customer search

  • id: Customer identifier with 'cust_' prefix for direct lookup

Validation Rules:

  • Exactly one parameter (email OR id) must be provided

  • Email must be valid email format

  • ID must start with 'cust_' prefix

Examples:

Returns: JSON object containing complete customer data including:

  • id, source_id, email, name

  • metadata (custom attributes)

  • loyalty summary (points, tier, etc.) when available

  • creation and update timestamps

Raises:

  • ToolError: If both/neither parameters provided, customer not found, or invalid format

ParametersJSON Schema
NameRequiredDescriptionDefault
idNo
emailNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations provided, the description carries full burden and delivers complete behavioral details: ID vs email lookup behavior, case-insensitive search, complete object return including loyalty summary, and error conditions. No contradictions.

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 well-structured with sections for lookup behavior, parameters, validation, examples, returns, and raises. It is front-loaded with the main purpose. Slightly verbose but every section adds value. Could be slightly more concise.

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

Completeness5/5

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

Given the simple task of finding a customer with two parameters, and an output schema present, the description fully covers the input requirements, validation, return data structure, and error handling. No gaps.

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

Parameters5/5

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

Schema coverage is 0% as the schema only provides type and default. The description compensates thoroughly by specifying exact validation rules (email format, id prefix cust_), requiring exactly one parameter, and providing examples. This adds significant meaning beyond the schema.

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

Purpose5/5

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

The description clearly states the verb 'Find' and resource 'customer', with explicit lookup methods by email or ID. It distinguishes itself from sibling tools like get_campaign and list_products by focusing on customer retrieval.

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 provides clear context on when to use the tool, including validation rules that exactly one parameter must be provided and format requirements. It implicitly indicates not to use when data is not a customer, but lacks explicit when-not or alternative tool references.

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

get_best_dealsA

Find top 5 best deal promotions for customer's order with validation analysis.

Analyzes order items against available promotions to identify highest-value deals. Returns promotions with validation rules - some may be partially valid, requiring additional items or changes to qualify for the discount.

Use Case: Upselling and cross-selling optimization

  • Identify best promotions for current cart

  • Determine what customer needs to add/change for qualification

  • Optimize cart value through targeted recommendations

Important: This tool is specialized for order-based promotion analysis. Do not combine with 'qualifications' tool as they serve different purposes.

Parameters: Parameters:

  • customer: đź”´ MANDATORY - Customer identification and profile data. This parameter is REQUIRED for every call.

  • order: đź”´ MANDATORY - Order with items list for promotion matching and analysis. This parameter is REQUIRED for every call.

Order Item Configuration: Each item can be specified in multiple ways:

  1. By Product ID (most precise): {"product_id": "prod_abc123", "price": 2000, "quantity": 1}

  2. By Source ID (requires related_object): {"source_id": "special-meal", "related_object": "product", "price": 3000, "quantity": 1}

  3. Generic with metadata (for product collection matching): {"quantity": 2, "product": {"metadata": {"category": "Electronics"}}}

  4. Price-less items (uses catalog price): {"source_id": "drink", "related_object": "product", "quantity": 1}

Pricing Rules:

  • All prices in cents (2000 = $20.00, 150 = $1.50)

  • Items without price use product catalog pricing

  • Quantity must be positive integer

Examples:

  • get_best_deals( customer={"id": "cust_abc123"}, order={ "items": [ {"product_id": "prod_112e92ce9a7cf5b1d8", "price": 2000, "quantity": 1}, {"source_id": "special-meal", "related_object": "product", "price": 3000, "quantity": 1} ] } )

Example of invalid usage:

  • get_best_deals()

Returns: JSON array of up to 5 promotion objects, each containing:

  • id: Promotion identifier

  • result: Qualification status (APPLICABLE, PARTIALLY_APPLICABLE, etc.)

  • is_applicable: Boolean indicating if given incentive meets all validation rules

  • redeemable_details: Promotion information (banner, description, campaign)

  • validation_rules: Array of validation requirements with status

  • resolved_order: Order with calculated totals and promotion effects if incentive is applicable

Each validation rule includes:

  • validation_rules_definition: Rule logic and requirements

  • validation_status: Current compliance status

  • validation_omitted_sub_rules: Missing requirements for qualification

See "Validation Rules Structure" section in server instructions for detailed rule format documentation

Raises:

  • ToolError: If customer missing required fields or order structure invalid

ParametersJSON Schema
NameRequiredDescriptionDefault
orderYes
customerYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

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

Despite no annotations, the description thoroughly explains behavior: it analyzes order items against promotions, returns validation results with partial applicability, details return structure, pricing rules, item configuration options, and error handling. No contradictions; fully transparent.

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

Conciseness4/5

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

The description is well-structured with sections (purpose, use case, important note, parameters, examples, returns, errors). Front-loaded with goal. Minor redundancy: 'Parameters:' appears twice. Otherwise efficient for the complexity.

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

Completeness5/5

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

Given the minimal schema and absence of annotations, the description covers all necessary aspects: parameter details, examples, return format, error handling, and differentiation from siblings. The output schema is not provided but its structure is described. Complete for a complex tool.

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

Parameters5/5

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

Input schema has no description coverage (0%), but the description compensates with detailed explanations for both parameters. It describes customer and order structure, provides four item configuration formats, pricing rules, examples, and required fields. Adds significant meaning beyond the minimal schema.

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

Purpose5/5

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

The description clearly states 'Find top 5 best deal promotions for customer's order with validation analysis.' It specifies the action (find best deals), resource (promotions), and scope (top 5). It explicitly distinguishes from the sibling 'qualifications' tool by warning not to combine them.

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

Usage Guidelines5/5

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

The description provides explicit use cases (upselling/cross-selling optimization) and includes a clear 'Important' note: 'Do not combine with 'qualifications' tool as they serve different purposes.' It guides when to use and when not to use.

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

get_campaignA

Retrieve detailed information about a specific campaign by its ID.

Returns complete campaign configuration including discount details, validation rules, voucher settings, and current status for campaign analysis and management.

Enhanced Features:

  • Automatically fetches and processes validation rules for detailed rule analysis

  • Provides both raw validation_rules_assignments and processed assigned_validation_rules

  • Includes complete campaign hierarchy and voucher generation settings

Parameters:

  • campaign_id: Campaign identifier for lookup

Identifier Requirements:

  • Campaign ID: Must start with 'camp_' prefix (e.g., "camp_X26jzR8ObD55nlwOUcr63Px0")

  • ID must correspond to existing campaign

Validation Rules:

  • Campaign ID must be valid and existing

  • ID format is case-sensitive

Examples:

  • get_campaign(campaign_id="camp_X26jzR8ObD55nlwOUcr63Px0")

Returns: JSON object containing complete campaign details including:

Core Campaign Information:

  • id: Campaign system identifier (e.g., "camp_X26jzR8ObD55nlwOUcr63Px0")

  • name: Human-readable campaign name (e.g., "Burger Deluxe Family Campaign")

  • campaign_type: Campaign type ("DISCOUNT_COUPONS", "GIFT_VOUCHERS", "LOYALTY_PROGRAM", "PROMOTION")

  • type: Campaign generation type ("STATIC", "DYNAMIC")

  • active: Boolean campaign status

  • object: Always "campaign"

Campaign Configuration:

  • auto_join: Boolean automatic customer enrollment setting

  • join_once: Boolean single enrollment restriction

  • use_voucher_metadata_schema: Boolean voucher metadata schema usage

  • protected: Boolean protection status against modifications

Voucher Template Settings:

  • voucher: Complete voucher template configuration:

    • type: Voucher type ("DISCOUNT_VOUCHER", "GIFT_VOUCHER", etc.)

    • discount: Discount configuration (e.g., {"type": "PERCENT", "percent_off": 3})

    • redemption: Usage limits (e.g., {"quantity": null} for unlimited)

    • code_config: Code generation settings:

      • length: Code length (e.g., 8)

      • charset: Character set for code generation

      • pattern: Code pattern (e.g., "########")

    • is_referral_code: Boolean referral code status

Campaign Status and Statistics:

  • vouchers_count: Total vouchers generated in campaign

  • creation_status: Campaign creation status ("DONE", "IN_PROGRESS", "FAILED")

  • vouchers_generation_status: Voucher generation status ("DONE", "IN_PROGRESS", "FAILED")

  • created_at: Campaign creation timestamp (ISO 8601)

Access and Categorization:

  • access_settings_assignments: Access control assignments with data array and total count

  • category_id: Campaign category identifier (null if uncategorized)

  • categories: Array of campaign categories (empty if uncategorized)

Validation Rules (Enhanced):

  • assigned_validation_rules: Processed validation rules with detailed conditions (added by this tool) See "Validation Rules Structure" section in server instructions for complete field documentation

Use Cases:

  • Analyze campaign configuration and discount mechanics

  • Understand validation rules and product requirements

  • Check campaign status and voucher generation progress

  • Review campaign hierarchy and settings

  • Get complete campaign blueprint for duplication

Raises:

  • ToolError: If campaign not found or invalid campaign ID format

ParametersJSON Schema
NameRequiredDescriptionDefault
campaign_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. It discloses enhanced features (fetching and processing validation rules), provides detailed return structure, and mentions error raising. Rich 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?

Description is long but well-structured with clear sections. Every sentence adds value, though it could be slightly more concise. Front-loaded with main purpose.

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

Completeness5/5

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

Given the single parameter and detailed output, the description is very complete. It covers purpose, parameter semantics, output structure, examples, use cases, and error handling. No gaps.

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

Parameters5/5

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

Only one parameter (campaign_id) and schema coverage is 0%, but description adds extensive meaning: identifier requirements, format ('camp_' prefix), case-sensitivity, examples, and validation rules.

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

Purpose5/5

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

Description clearly states 'Retrieve detailed information about a specific campaign by its ID.' It uses specific verb and resource. It distinguishes from siblings like list_campaigns (list all) and get_campaign_summary (summary).

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?

Description lists use cases like analyzing campaign configuration and validation rules. While it doesn't explicitly say when not to use or contrast with alternatives, the context is clear enough for an agent to decide.

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

get_campaign_summaryA

Retrieve comprehensive analytics summary for a specific campaign.

Returns detailed statistics including validations, redemptions, publications, and campaign-type-specific metrics for performance analysis.

Parameters:

  • campaign_id: Valid campaign identifier with 'camp_' prefix

  • start_date: Optional analysis period start (ISO 8601 date format)

  • end_date: Optional analysis period end (ISO 8601 date format)

Date Parameter Rules:

  • Both start_date and end_date must be provided together or omitted together

  • Empty strings are invalid - use null/None for no date filtering

  • Omitting both dates returns full campaign period summary

  • Date format: YYYY-MM-DD (e.g., "2025-01-01")

Examples:

  • get_campaign_summary(campaign_id="camp_aPVb581gdJ1xF6esnDnDocVK")

  • get_campaign_summary( campaign_id="camp_aPVb581gdJ1xF6esnDnDocVK", start_date="2025-01-01", end_date="2025-01-31" )

Examples of bad usage:

  • get_campaign_summary(campaign_id="camp_aPVb581gdJ1xF6esnDnDocVK", start_date="", end_date="")

Returns: JSON object containing campaign analytics including:

  • validations: Validation attempt statistics

  • redemptions: Successful redemption counts and values

  • publications: Voucher distribution metrics

  • campaign_type specific metrics (varies by campaign type)

  • date range information

  • performance indicators

Raises:

  • ToolError: If campaign not found, invalid date format, or mismatched date parameters

ParametersJSON Schema
NameRequiredDescriptionDefault
end_dateNo
start_dateNo
campaign_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden. It details parameter constraints (paired dates, format) and error conditions (ToolError for invalid inputs). It does not mention potential side effects or performance, but as a read-only analytics tool, the transparency is adequate.

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 well-structured with separate sections for parameters, rules, examples, and returns. It is front-loaded with the core purpose. Some redundancy exists (date rules repeated), but overall it is clear and informative.

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

Completeness5/5

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

Given the tool's moderate complexity, no annotations, and existence of an output schema, the description covers usage, parameter constraints, examples, errors, and return structure comprehensively. It leaves little ambiguity for an AI agent.

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

Parameters5/5

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

Schema description coverage is 0%, but the description compensates fully. It explains the campaign_id prefix, date format (ISO 8601), the rule that both dates must be provided together or omitted, and invalid empty strings. This adds significant meaning beyond the schema's type/title.

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

Purpose5/5

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

The description clearly states the tool retrieves a comprehensive analytics summary for a specific campaign, detailing included metrics like validations, redemptions, and publications. This distinguishes it from sibling tools such as get_campaign (basic info) and list_campaigns (listing).

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 provides explicit examples and parameter rules, including when to omit dates. It does not directly state when not to use this tool versus alternatives, but the context from sibling names and the detailed explanation of analytics scope implies appropriate use cases.

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

get_promotion_tierA

Retrieve detailed information about a specific promotion tier by its ID.

Returns complete promotion tier configuration including discount rules, validation criteria, and metadata for promotion analysis and management.

Enhanced Features:

  • Automatically fetches and processes validation rules for detailed rule analysis

  • Provides both raw validation_rules_assignments and processed assigned_validation_rules

  • Includes complete promotion tier hierarchy and action settings

Parameters:

  • promotion_tier_id: Promotion tier identifier for lookup

Identifier Requirements:

  • Promotion Tier ID: Must start with 'promo_' prefix (e.g., "promo_abc123def456")

  • ID must correspond to existing promotion tier

Validation Rules:

  • Promotion tier ID must be valid and existing

  • ID format is case-sensitive

Examples:

  • get_promotion_tier(promotion_tier_id="promo_abc123def456")

Returns: JSON object containing complete promotion tier details including:

Core Promotion Tier Information:

  • id: Promotion tier system identifier (e.g., "promo_abc123def456")

  • name: Human-readable tier name

  • banner: Display banner text for promotion

  • object: Always "promotion_tier"

Discount Configuration:

  • action: Complete discount configuration including:

    • discount: Discount type and value settings

    • unit_off: Fixed amount discount (if applicable)

    • unit_off_formula: Dynamic discount calculation (if applicable)

    • percent_off: Percentage discount (if applicable)

    • percent_off_formula: Dynamic percentage calculation (if applicable)

Promotion Settings:

  • hierarchy: Tier ordering and priority within campaign

  • campaign: Parent campaign information

  • campaign_id: Parent campaign identifier

  • summary: Promotion tier summary and statistics

Validation Rules (Enhanced):

  • assigned_validation_rules: Processed validation rules with detailed conditions (added by this tool) See "Validation Rules Structure" section in server instructions for complete field documentation

Additional Data:

  • metadata: Custom promotion tier attributes

  • created_at, updated_at: ISO 8601 timestamps

Use Cases:

  • Analyze promotion tier configuration and discount mechanics

  • Understand validation rules and eligibility requirements

  • Review promotion tier hierarchy and priority

  • Get complete promotion tier blueprint for management

  • Check promotion tier status and performance

Raises:

  • ToolError: If promotion tier not found or invalid ID format

ParametersJSON Schema
NameRequiredDescriptionDefault
promotion_tier_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

Since no annotations are provided, the description bears full burden. It discloses that the tool automatically fetches and processes validation rules, provides processed data, and raises ToolError for invalid inputs. It could explicitly state it's a read-only operation, but the behavior is well-described.

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 long but well-structured with clear sections (Overview, Enhanced Features, Parameters, etc.). It is front-loaded with the core purpose. While some detail could be condensed, the organization aids readability and every section adds value.

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

Completeness5/5

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

Given the tool's single parameter, no output schema, and unrelated siblings, the description covers the tool's purpose, parameters, return structure (with detailed fields), use cases, and error handling. It is comprehensive for the tool's simplicity.

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

Parameters5/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 thoroughly documents the parameter's purpose, required format (must start with 'promo_'), case sensitivity, and validity requirement. It also provides an example that clarifies the expected format.

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

Purpose5/5

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

The description clearly states the action ('Retrieve detailed information') and the resource ('specific promotion tier by its ID'). It distinguishes the tool's purpose from siblings like get_voucher and get_campaign by focusing on promotion tier details.

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 provides explicit use cases (e.g., 'Analyze promotion tier configuration', 'Understand validation rules'), a concrete example, and identifier requirements. It does not explicitly state when not to use this tool or mention alternatives, but the use cases strongly imply appropriate contexts.

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

get_voucherA

Retrieve detailed information about a specific voucher by its code or ID.

Returns complete voucher configuration including discount details, usage limits, validation rules, and current status for voucher analysis and management.

Enhanced Features:

  • Automatically fetches and processes validation rules for detailed rule analysis

  • Provides both raw validation_rules_assignments and processed validation_rules

  • Includes QR/barcode assets for voucher display and distribution

Parameters:

  • identifier: Voucher code or ID for lookup

Identifier Types:

  • Voucher Code: Human-readable code with alphanumeric and special characters (e.g., "WELCOME10", "SAVE20", "TEST-ABC")

  • Voucher ID: System identifier with 'v_' prefix (e.g., "v_abc123def456")

Validation Rules:

  • Identifier must correspond to existing voucher

  • Both codes and IDs are case-sensitive

Examples:

  • get_voucher(identifier="WELCOME10")

  • get_voucher(identifier="v_abc123def456")

Returns: JSON object containing complete voucher details including:

Core Voucher Information:

  • id: Voucher system identifier (e.g., "v_4dyaDRCMD0bUDNv47pDqnGlCJhSVWtnT")

  • code: Human-readable voucher code (e.g., "DELUXE-SG63RY")

  • type: Voucher type ("DISCOUNT_VOUCHER", "GIFT_VOUCHER", "LOYALTY_CARD")

  • active: Boolean voucher status

  • object: Always "voucher"

Discount Configuration:

  • discount: Discount details with type and value (e.g., {"type": "PERCENT", "percent_off": 25})

  • gift: Gift voucher amount (null for discount vouchers)

  • loyalty_card: Loyalty card details (null for regular vouchers)

Validity and Constraints:

  • start_date, expiration_date: Validity period (ISO 8601 or null)

  • validity_timeframe, validity_hours: Time-based restrictions

  • validity_day_of_week: Array of valid weekdays (1=Monday, 7=Sunday)

Usage Tracking:

  • redemption: Usage statistics with quantity limits and current usage

  • publish: Publication information and count

  • holder_id: Customer ID if voucher is assigned

Campaign and Categorization:

  • campaign, campaign_id: Parent campaign information (null for standalone vouchers)

  • category, category_id, categories: Voucher categorization

Validation Rules (Enhanced):

  • assigned_validation_rules: Processed validation rules with detailed conditions (added by this tool) See "Validation Rules Structure" section in server instructions for complete field documentation

Additional Data:

  • metadata: Custom voucher attributes

  • additional_info: Extra voucher information

  • assets: QR code and barcode URLs for voucher display

  • is_referral_code: Boolean indicating referral voucher

  • created_at, updated_at: ISO 8601 timestamps

Use Cases:

  • Verify voucher validity and details

  • Check voucher usage and limits

  • Analyze voucher configuration and discount mechanics

  • Understand validation rules and product requirements

  • Check voucher ownership and assignment

  • Get QR/barcode assets for voucher display

Raises:

  • ToolError: If voucher not found or invalid identifier format

ParametersJSON Schema
NameRequiredDescriptionDefault
identifierYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations provided, the description fully covers behavior: it discloses automatic processing of validation rules, return structure, and error conditions (raises ToolError). It also describes the 'Enhanced Features' that add value beyond a simple lookup.

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 fairly long but well-structured with clear sections (Enhanced Features, Parameters, Examples, Returns, Use Cases). It is front-loaded with purpose. Some redundancy exists (e.g., repeating identifier types), but overall it is organized and informative.

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

Completeness5/5

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

For a single-parameter tool with a complex return (many fields), the description provides a detailed breakdown of all return fields, error handling, and use cases. It also references external documentation for validation rules. Given the output schema exists, the description adds significant contextual completeness.

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

Parameters5/5

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

The single parameter 'identifier' has 0% schema description coverage, but the description compensates richly: it explains both identifier types (code vs ID), case-sensitivity, validation rules, and provides examples. This fully documents the parameter's semantics.

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

Purpose5/5

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

The description explicitly states 'Retrieve detailed information about a specific voucher by its code or ID.' It clearly identifies the verb (retrieve), resource (voucher), and scope (specific voucher via code or ID). This distinguishes it from sibling tools like 'list_campaigns' or 'find_customer'.

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 includes explicit use cases, examples, and identifier type guidance. It does not explicitly state when not to use or contrast with siblings, but the 'Use Cases' section provides context for appropriate usage.

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

list_campaignsA

List all campaigns with basic information for campaign resolution.

Primary Use Case: Resolve campaign ID when user provides only campaign name or partial name. Returns comprehensive list of all campaigns for further name-based matching.

Behavior:

  • Retrieves all campaigns (up to 1000) in single request

  • No filtering - returns complete campaign catalog

  • Avoid multiple calls as results are comprehensive

No Parameters Required: This tool requires no input parameters and returns all available campaigns.

Returns: JSON array of campaign objects, each containing:

  • id: Campaign identifier starting with 'camp_'

  • name: Human-readable campaign name

  • campaign_type: Campaign type (e.g., 'DISCOUNT_COUPONS', 'GIFT_VOUCHERS')

  • created_at: ISO 8601 creation timestamp

Example Output: [ { "id": "camp_abc123def456", "name": "Summer Sale 2025", "campaign_type": "DISCOUNT_COUPONS", "created_at": "2025-01-01T00:00:00.000Z" }, { "id": "camp_xyz789ghi012", "name": "Holiday Promotions", "campaign_type": "GIFT_VOUCHERS", "created_at": "2024-12-01T00:00:00.000Z" } ]

Usage Pattern:

  1. Call list_campaigns() to get all campaigns

  2. Match user's campaign name against returned names

  3. Use resolved campaign ID for other campaign tools

Limitations:

  • Maximum 1000 campaigns returned

  • No filtering options available

  • Results sorted by creation date

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. Clearly states behavior: retrieves up to 1000 campaigns, no filtering, single request, sorted by creation date. Includes limitations and example output.

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?

Description is verbose but well-structured with sections (primary use case, behavior, no parameters, returns, example, usage pattern, limitations). Every sentence adds value; front-loaded with key information.

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

Completeness5/5

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

Tool has no parameters and output schema exists (example given). Description covers purpose, behavior, limitations, usage pattern, and return structure. Completely adequate for a simple list 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?

No parameters, schema coverage 100%. Baseline 4 for 0 params. Description adds value by explicitly stating no parameters needed and explaining that no input is required.

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

Purpose5/5

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

Description clearly states it lists all campaigns for campaign resolution, with specific verb 'list' and resource 'campaigns'. Distinguishes from siblings like get_campaign by returning comprehensive list for name-based matching.

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?

Explicit primary use case is resolving campaign ID from name. Provides usage pattern and warns against multiple calls. Does not explicitly state when NOT to use, but limitations (no filtering) imply alternatives may be needed for filtered results.

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

list_productsA

List products with optional filtering and pagination.

Returns paginated product catalog with flexible filtering capabilities for product discovery, inventory analysis, and catalog management.

Parameters:

  • filters: Optional filter criteria using field paths and operators

  • page: Optional page number (default: 1, provide only for page 2+)

Filter Structure: { "field_path": { "conditions": { "$operator": "value" } } }

Supported Fields:

  • name: Product name (string)

  • source_id: External product identifier (string)

  • price: Product price in cents (integer)

  • created_at: Creation date (ISO 8601)

  • metadata.: Custom metadata fields (various types)

Operators by Field Type: String fields (name, source_id, metadata):

  • $is, $is_not: Exact match

  • $contains, $starts_with: Partial match

  • $in: Match any from array

Numeric fields (price, numeric metadata):

  • $more_than, $less_than: Comparison

  • $more_than_equal, $less_than_equal: Inclusive comparison

Date fields (created_at):

  • $after, $before: Date comparison (ISO 8601 format)

Pricing Rules:

  • All prices in cents (2000 = $20.00, 150 = $1.50)

  • Consistent across all Voucherify tools

Examples:

  • list_products() # All products, page 1

  • list_products(page=2) # All products, page 2

  • list_products( filters={ "metadata.category": {"conditions": {"$is": "Electronics"}}, "price": {"conditions": {"$more_than": 5000}} } )

  • list_products( filters={ "name": {"conditions": {"$contains": "Premium"}}, "created_at": {"conditions": {"$after": "2025-01-01"}} }, page=3 )

Returns: JSON object containing:

  • products: Array of product objects with full details

  • total: Total number of matching products

  • has_more: Boolean indicating if more pages available

  • Each product includes: id, name, source_id, price, metadata, timestamps

Pagination:

  • 100 products per page

  • Results sorted by created_at descending (newest first)

  • Custom sorting not supported

Raises:

  • ToolError: If filter structure invalid or unsupported operators used

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
filtersNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. It fully discloses pagination behavior (100 per page, sorted by created_at descending), pricing conventions (cents), return structure (products, total, has_more), error handling (ToolError for invalid filters), and limitations (no custom sorting). No contradictions.

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?

Well-structured and front-loaded with core purpose. While lengthy, each section (params, filters, operators, examples, return, errors) adds unique value. Could be slightly tighter but remains effective and easy to scan.

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

Completeness5/5

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

Given 2 optional parameters, no schema descriptions, and no output schema provided, the description covers all necessary aspects: purpose, parameters, filter semantics, return format, pagination, pricing, and error conditions. It is fully self-contained for an AI agent to invoke correctly.

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

Parameters5/5

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

Schema has 0% description coverage, so description compensates fully. It explains both parameters: page (optional, default 1, hint for page 2+) and filters (detailed structure with supported fields, operators by type, and multiple examples). Adds meaning far beyond the raw schema.

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

Purpose5/5

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

Clearly states 'List products with optional filtering and pagination.' The verb 'list' and resource 'products' are specific. The description distinguishes this tool from siblings (which handle customers, campaigns, vouchers, etc.) by focusing on product catalog operations.

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

Usage Guidelines5/5

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

Provides explicit guidance: use for product discovery, inventory analysis, catalog management. Details parameter usage, filter structure, operators, and examples. Includes exclusions like 'Custom sorting not supported' and error conditions, leaving no ambiguity about when and how to use.

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

qualificationsA

Find redeemables (vouchers, promotions, campaigns) applicable to given customer.

⚠️ CRITICAL: The 'customer' parameter is ALWAYS REQUIRED - never call this tool without it!

Returns list of available discounts, vouchers, and promotions based on customer profile and selected scenario for targeted marketing and cart optimization.

Parameters:

  • customer: đź”´ MANDATORY - Customer identification and profile data. This parameter is REQUIRED for every call.

  • scenario: đź”´ MANDATORY - Qualification scope determining which redeemables to evaluate (optional, defaults to ALL)

Customer Object Structure: Required (one of):

  • id: Customer ID with 'cust_' prefix (e.g., "cust_abc123")

  • source_id: External customer identifier Optional:

  • metadata: Dict of custom customer attributes for rule matching

Scenario Guide (Choose Based on Use Case):

CUSTOMER-FOCUSED:

  • ALL: Scenario that returns redeemables available for the customer

  • CUSTOMER_WALLET: returns vouchers applicable to the customer's cart based on the vouchers assigned to the customer's profile

  • AUDIENCE_ONLY: returns all vouchers, promotion tiers, and campaigns available to the customer. It validates the rules based on the customer profile only.

PRODUCT-FOCUSED (require product context in other tools):

  • PRODUCTS: returns all promotions available for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule)

  • PRODUCTS_DISCOUNT: returns all promotions available for products when a discount is defined as applicable to specific item(s).

  • PRODUCTS_BY_CUSTOMER: returns all promotions available for a customer for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule).

  • PRODUCTS_DISCOUNT_BY_CUSTOMER: returns all promotions available for a customer for products when a discount is defined as applicable to specific item(s).

ADVANCED:

  • PROMOTION_STACKS: returns the applicable promotion stacks

Common Usage Patterns:

  • Customer wallet check: Use CUSTOMER_WALLET

  • Matching redeemables to given context: Use ALL

  • Customer-based targeting: Use AUDIENCE_ONLY

âś… CORRECT Examples (always include customer):

  • qualifications(customer={"id": "cust_abc123"}, scenario="CUSTOMER_WALLET")

  • qualifications(customer={"source_id": "user_456", "metadata": {"tier": "gold"}})

  • qualifications(customer={"id": "cust_xyz789"}, scenario="ALL")

  • qualifications(customer={"id": "cust_abc123"}) # scenario defaults to ALL

đźš« WRONG Examples (missing required customer parameter):

  • qualifications() # ❌ NEVER do this - customer is required

  • qualifications(scenario="CUSTOMER_WALLET") # ❌ NEVER do this - customer is required

  • qualifications(scenario="ALL") # ❌ NEVER do this - customer is required

đź’ˇ Remember: ALWAYS provide the customer parameter - it's never optional!

Returns: JSON object containing:

  • redeemables: Array of applicable vouchers/promotions

  • Each redeemable includes: id, name, discount details, validation rules

  • Scenario-specific filtering applied

Raises:

  • ToolError: If customer missing required fields or invalid scenario

ParametersJSON Schema
NameRequiredDescriptionDefault
customerYes
scenarioNoALL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

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

The description covers return format, error handling (ToolError), and critical warnings about required parameter. It does not explicitly state read-only nature or auth requirements, but provides good transparency overall.

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 quite verbose with multiple sections and emojis. While well-structured, it could be more concise without losing value.

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

Completeness5/5

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

Given the tool's complexity (2 parameters, nested objects), the description is complete: it covers all scenarios, provides correct/wrong examples, and explains return values and errors. Output schema exists but description still adds value.

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

Parameters5/5

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

Given low schema description coverage, the description adds significant meaning: it details the customer object structure (required fields, optional metadata) and explains each scenario value with its purpose, vastly exceeding the schema's minimal type definitions.

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 finds redeemables applicable to a given customer, which is specific and distinguishes it from sibling tools like get_voucher or get_campaign.

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 provides extensive guidance on when to use each scenario (CUSTOMER_FOCUSED, PRODUCT_FOCUSED, ADVANCED) with common usage patterns. It also emphasizes that customer is always required. However, it does not explicitly exclude cases where sibling tools might 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. Dates show when Glama detected each change.

  1. 10 tool updatesv0.1.0
    • First observedestimate_loyalty_points
    • First observedfind_customer
    • First observedget_best_deals
    • First observedget_campaign
    • First observedget_campaign_summary
    • First observedget_promotion_tier
    • First observedget_voucher
    • First observedlist_campaigns
    • First observedlist_products
    • First observedqualifications
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool targets a distinct resource or operation: customer lookup, campaign retrieval/listing/summary, promotion tier, voucher, qualifications, best deals, loyalty points, and product listing. Even overlapping areas like qualifications and get_best_deals are clearly differentiated by descriptions and use cases.

Naming Consistency4/5

Most tools follow a verb_noun pattern (get_campaign, list_campaigns, find_customer, etc.). The outlier is 'qualifications', which is a noun without a verb prefix, but overall the pattern is consistent and predictable.

Tool Count5/5

10 tools is well-scoped for a core API server covering customers, campaigns, promotion tiers, vouchers, qualifications, deals, loyalty points, and products. It provides essential operations without being overwhelming.

Completeness2/5

The tool set is entirely read-only; there are no create, update, or delete operations for any resource (customers, campaigns, vouchers, products, etc.). Additionally, listing tools are missing for vouchers and promotion tiers. This creates significant gaps for agents needing to manage resources.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/voucherifyio/core-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server