Known MCP Limitations

Use these limitations when designing an integration. For handling patterns and examples, see Reliability, Errors, and Pagination.

Area	Current constraint	What to do
Search validation	Some invalid requests return a generic HTTP 400 message without identifying the offending field.	Check each field and operator through `cb_reference`; simplify one predicate at a time.
Error envelope	Transport, MCP, and tool-payload errors are separate layers.	Check all layers before reading result rows.
Empty results	Zero rows may arrive without predicate, coverage, or access diagnostics.	Validate identifiers and scope; do not equate zero matches with absence in the real world.
Expert answer shaping	The question input has no explicit row-limit, selected-field, deduplication, or continuation parameter.	Use natural language to express intent; use structured search when you need explicit retrieval controls.
Expert interpretation	The planner can narrow the answered question.	Surface `answered_question` when supplied.
Profile selections	Unknown or unavailable fields/cards can be omitted without an error.	Validate selections and compare requested versus returned content; missing does not mean empty.
Related-entity budget	`related_entity_limit` is not a strict combined row cap across multiple cards.	Select cards explicitly and enforce application-level payload safeguards.
Input limits	Validation can occur in the client or server, and out-of-range handling varies by input.	Use supported values; do not rely on rejection or normalization of invalid values.
Entity resolution	Company domains are unsuitable for person lookups and may yield the wrong entity or no candidates.	Use a person collection, name, and context for person resolution.
Card continuation	No per-card total or effective page-size field is exposed. Single-card responses are capped at 100 or a lower applicable card/access limit; continuation can reflect budget clipping or an exactly full page.	Fetch one card at a time, inspect the flag, and guard against empty pages and repeated cursors.
Multi-page consistency	These docs provide no snapshot-isolation or cursor-lifetime guarantee.	Keep the query unchanged, deduplicate UUIDs, and label interrupted traversals as incomplete.
Request correlation	Request IDs are useful for support but are not an application-level uniqueness guarantee. Some tools do not expose one.	Record your own invocation ID, timestamp, and tool name as well.
Write retries	Idempotency and exactly-once execution are not specified for list writes or feedback.	Inspect state before retrying an uncertain write.
Programmatic access	A registered OAuth client is not a service identity.	Arrange unattended or shared access with your Customer Success Manager.
Data tokens	`cb_metering_get_state` reports the user’s data-token allowance, not every access or rate limit.	Inspect allowance and reset time when supplied; handle other error types separately. Unknown is not unlimited.
Knowledge Center answers	Generated answers can omit current source details or mix REST and MCP guidance.	Open canonical MCP pages and check live tool schemas; do not assume publication immediately refreshes answers.

Guidance examples

Prefer the live per-field reference when constructing predicates. Identifier filters need returned UUIDs or permalinks; do not copy display names such as "San Francisco" into identifier-valued predicates.

A relationship subquery requires the appropriate relationship collection and nested query shape. If an example cannot be validated for your use case, obtain a compiled search with cb_expert_build_search, review its scope, and replay it through cb_search_query.

Reporting a problem

Contact your account team or Customer Success Manager with the UTC timestamp, client/version, tool name, redacted arguments, error code/message, and request ID when available. Describe whether the problem is a failed call, an unexpected interpretation, or an incomplete traversal.

Transient failures are not permanent capability restrictions. Retry recommendations and current observations are not uptime or recovery guarantees.