> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxpressd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cigar-band matching

> Identify a cigar from band images with Presston AI MCP tools.

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:

```text theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/presston-mcp/billing) for the error flow.