Best Practices

Strategies for getting the most out of HTS MCP’s search, enrichment, and graph capabilities.

Search Strategy Selection

When to Use Hybrid (Default)

Hybrid search combines 70% semantic similarity with 30% lexical matching. Use it for:

• Most general-purpose queries
• Product descriptions in natural language
• When you’re unsure which strategy is best

When to Use Semantic

Pure semantic search relies entirely on embedding similarity. Use it for:

• Vague or conceptual queries (“things related to agriculture”)
• When lexical terms don’t match official HTS descriptions
• Cross-language or paraphrased queries

When to Use Lexical

Lexical search uses ILIKE pattern matching. Use it for:

• Known HTS terminology (“bovine animals, fresh or chilled”)
• Exact product names
• When speed matters more than recall (lexical is faster)

Multi-Level Search

Search at different hierarchy levels depending on your goal:

The full variant includes section and chapter context in the embedding text, which helps with disambiguation. Use short when you want direct description-to-description similarity without hierarchical context.

Working with the Knowledge Graph

Confidence Thresholds

Graph edges have a confidence score from 0 to 1. Recommended thresholds:

Filtering by Relationship Type

Filter results to specific relationship types for focused analysis:

• Classification research: substitution, cross_category_bridge
• Supply chain analysis: component_assembly, end_use, manufacturing_process
• Product alternatives: functional_similarity, material_affinity

Caching Behavior

• Tariff lookups (get_tariff) are cached with LRU (TTL: 1 hour)
• Tariff counts are cached (TTL: 5 minutes)
• Embedding availability checks are cached
• Search results are not cached, each query runs fresh

Authentication (REST API)

The REST API supports optional API key authentication:

GET /api/v1/search?query=steel
Authorization: Bearer your-api-key

Set API_KEY in your environment to enable authentication. If not set, the API runs without authentication.

Rate Limits (REST API)

When RATE_LIMIT_ENABLED=true: