Agent Best Practices

Whether you're using MCP with Claude, the OpenAI Responses API with LangChain, or any other agent framework — these patterns will help you build more effective and reliable Catalogian integrations.

Always profile before querying

Call profile_snapshot before interacting with a source for the first time. It returns field names, types, cardinality, null rates, and sample values — critical context for the LLM to construct meaningful queries.

// Good: profile first, then query
const profile = await callTool("profile_snapshot", { sourceSlug: "acme-products" });
// Now the agent knows: fields are [sku, name, price, brand, category, in_stock]
// and can write targeted filter/search queries

// Bad: querying blind
const results = await callTool("search_snapshot", {
  sourceSlug: "acme-products",
  query: "nike"
});
// Works, but the agent doesn't know what fields exist for follow-up questions

Use source slugs, not IDs

All tools accept sourceSlug — a human-readable identifier like acme-products. Slugs are easier for agents to remember and reason about than opaque IDs.

// Good
{ "sourceSlug": "acme-products" }

// Works but harder for agents to track
{ "sourceSlug": "cmmfyryl30005ygld7m5596gm" }

You can find a source's slug via list_sources — it's included in the response.

Choose the right tool

Catalogian exposes 16 tools. Use the right one for the job:

• •Discovery: list_sources → profile_snapshot → snapshot_schema
• •What changed? get_delta → get_delta_rows for details
• •Find specific products: search_snapshot for keyword search, filter_snapshot_rows for structured filters
• •Aggregate data: query_snapshot for counts, distinct values, group-by, min/max/avg/sum
• •Representative sample: sample_snapshot with stratifyBy for balanced sampling
• •Export: download_snapshot or download_filtered_snapshot for CSV/JSON exports
• •Health check: get_health for source diagnostics

Write effective system prompts

Include these instructions in your agent's system prompt:

You have access to Catalogian, a product feed monitoring service.

Rules:
1. Always call profile_snapshot before analyzing a source for the first time
2. Use source slugs (e.g. "acme-products") not IDs
3. When reporting changes, include specific before/after values
4. If a search returns no results, try broader terms or check the source slug
5. For large result sets, use limit parameters to avoid overwhelming context

Handle pagination in agents

Many tools return paginated results. When the response includes hasMore: true, you can fetch the next page. But in most agent workflows, the first page is sufficient — agents work better with focused context than exhaustive data.

Respect rate limits

MCP and Responses API calls are limited to 30 requests per minute per key. For agent workflows that make many tool calls:

• • Batch related queries where possible
• • Use query_snapshot for aggregations instead of fetching all rows
• • Cache profile_snapshot results for the duration of a conversation
• • Free plans: 50 MCP calls/day — paid plans: unlimited

Handle errors gracefully

Tools can return errors (source not found, rate limited, etc.). Your agent should handle these:

// In your tool executor, check for error responses
const result = await callTool("get_delta", { sourceSlug: "nonexistent" });
// If result contains "error", the agent should report it to the user
// rather than trying to parse it as data

Working with multiple sources

Start with list_sources to discover available sources, then work with specific ones. When building monitoring agents, iterate through sources and check each one:

# Agent workflow for monitoring all sources:
1. list_sources → get all source slugs
2. For each source:
   a. get_delta(sourceSlug, limit=1) → check for recent changes
   b. If changes detected: get_delta_rows for details
   c. Compile summary
3. Report findings to user