Cigar-band matching

Use identify_band when you want the complete matching workflow. It combines local visual search, visible text, structured band evidence, catalog validation, and bounded research when needed.

Complete workflow

Attach a reachable image URL and ask your client:

Identify the cigar in this band image. Return a confirmed catalog match only when the evidence is strong. Otherwise show the best suggestions and explain what would help distinguish them.

The client calls identify_band with input like:

{
  "imageUrl": "https://your-cdn.example/cigars/scan-1842.jpg",
  "prompt": "The photo shows the front of the band in daylight.",
  "suggestionLimit": 5,
  "researchMode": "auto",
  "researchProfile": "quick"
}

The result uses matched, suggestions, or unmatched. A match or suggestion with a cigar ID has been reloaded from the current Boxpressd catalog. A sourced result without a catalog ID appears as a pending suggestion for confirmation and later review.

Multi-cigar photos

Call detect_cigar_regions first when one photo contains several cigars:

{
  "imageUrl": "https://your-cdn.example/cigars/tray-2026-09-10.jpg",
  "minConfidence": 0.2,
  "maxDetections": 20,
  "paddingFraction": 0.1
}

The result contains ordered JPEG data URI crops. Run identify_band once for each crop. A valid image with no confident cigar regions returns an empty cigars array instead of an error.

Inspect each stage

Use staged tools when your interface shows evidence or lets a user confirm ambiguous results:

Call find_similar_cigars, recognize_cigar_text, and fingerprint_cigar_image with the same image.
Pass the complete fingerprint to match_cigar_fingerprint.
If close candidates remain, call analyze_band with the fingerprint and candidates.
Pass complete stage responses to identify_band under stageResults.

{
  "fingerprint": {
    "schemaVersion": "band-appearance-v2",
    "bandAppearance": {
      "backgroundColors": [
        { "color": "red", "confidence": 0.96, "prominence": 0.82 }
      ],
      "borderColors": [
        { "color": "gold", "confidence": 0.91 }
      ]
    }
  },
  "candidates": [
    { "cigarId": 101, "brand": "Diesel", "name": "Unlimited", "score": 0.78 },
    { "cigarId": 102, "brand": "Diesel", "name": "Wicked", "score": 0.76 }
  ],
  "expandSameBrand": true
}

Use the complete fingerprint returned by the tool. The abbreviated object above shows only the relevant shape. Band analysis changes the ranking only when stored color-role evidence is decisive. It can reject the candidate set without inventing a new match. Visible printed cigar-name text stays authoritative when it conflicts with palette evidence.

Wrapper variants

Call analyze_cigar_wrapper when candidates describe the same cigar identity with different wrappers, such as Natural and Maduro.

{
  "imageUrl": "https://your-cdn.example/cigars/wrapper-1842.jpg",
  "candidates": [
    {
      "cigarId": 201,
      "brand": "Sample Brand",
      "name": "Anniversary Natural",
      "wrapper": { "shade": "Natural", "type": "Connecticut" }
    },
    {
      "cigarId": 202,
      "brand": "Sample Brand",
      "name": "Anniversary Maduro",
      "wrapper": { "shade": "Maduro", "type": "Broadleaf" }
    }
  ]
}

The tool discriminates among supplied variants. It does not search for a different cigar. An inconclusive result leaves both candidates available for user selection.

Retry paid calls

The MCP server creates idempotent Developer API requests for paid tools. If a call fails because credits or entitlement are unavailable, it stops before the protected AI work. See MCP billing for the error flow.

Getting started

Tools and examples

Billing

Complete workflow

Multi-cigar photos

Inspect each stage

Wrapper variants

Retry paid calls

​Complete workflow

​Multi-cigar photos

​Inspect each stage

​Wrapper variants

​Retry paid calls

Complete workflow

Multi-cigar photos

Inspect each stage

Wrapper variants

Retry paid calls