📜Contract Tools
The May 2026 discovery and contract surface — how LLM clients introspect the server before making expensive calls.
In May 2026 the vCon MCP server added a family of six tools designed specifically for LLM clients that don't know what they're talking to in advance. They let a client ask "what do you support?", "what shape will you return?", and "what's your controlled vocabulary?" before making queries that might fail or return junk.
These are the contract tools: vcon_fetch, vcon_search, vcon_capabilities, vcon_taxonomy, vcon_graph_shape, and describe_response_shape. Together they give an LLM enough information to write accurate, token-budget-aware queries against any deployment of the server, regardless of its specific extensions, tag vocabulary, or attached domain conventions.
Why they exist
The pre-2026 MCP surface (and most MCP servers in general) assumes the client knows the server's shape ahead of time. That assumption breaks when an LLM is the client:
The model doesn't always know which extensions a particular server supports.
The model can't reliably guess how a server normalizes things like dealer IDs or campaign names.
Token-budget-aware clients need to know the response shape before receiving the response, or they'll overflow context windows.
LLMs are bad at offset-based pagination — they need cursor-based.
The contract tools fix this by exposing the server's contract explicitly. A well-behaved LLM client calls one or more of them once per session and caches the result.
Stable response envelopes
All contract tools use one of two envelope shapes — predictable across tools, predictable across versions:
Single-item (fetch):
{
"ok": true,
"item": { ... }
}Multi-item (search, list):
Error:
If a client encounters ok: false, it can recover from a clean structured error. The previous design returned partial / malformed results in the same shape as success, which an LLM had no way to detect.
The six tools
vcon_capabilities
vcon_capabilitiesReturns what this server supports:
supported_includes— the field groupsvcon_fetchandvcon_searchunderstand:core,parties,summary,tags,dealer,counts,dialog,analysis,attachmentssearch_modes—metadata,keyword,semantic,hybridpagination_semantics— confirms cursor-based pagination, names the cursor fieldbyte_budgets— the default and max values ofmax_response_bytesmigration_hints— notes about any active field-name migrations (see Field-Name Migration)
Call this first. Cache the result for the session.
vcon_taxonomy
vcon_taxonomyReturns the controlled vocabulary the database actually uses:
portal_taxonomy— domain-specific enum values surfaced by this deployment (e.g. a portal with categoriescomplaint,inquiry,praise)common_tag_keys— the tag keys that appear in the corpus, with sample valuesattachment_types— recognized attachment purposes, including extension-defined ones likestrolid_dealerpreferred_fields— hints about which fields the deployment expects to be populated
LLMs use this to write better filters. Without it, the model would guess values; with it, the model knows the real surface area.
vcon_graph_shape
vcon_graph_shapeReturns a live picture of how data is shaped in this corpus — not what's theoretically possible, but what's actually present:
The shape evolves with the deployment. Use it when an LLM needs to ground its assumptions about analysis types and tag keys in what's really there.
describe_response_shape
describe_response_shapeGiven a tool name, returns the JSON Schema (or equivalent) of the response that tool will produce, plus a concrete example payload. Use this when:
Your client needs to parse the response into typed objects.
You're building a multi-step plan and need to know which fields will be available downstream.
You're operating under a token budget and need to limit what to ask for.
Calling without a tool_name returns the list of tools with published shapes.
vcon_fetch
vcon_fetchThe contract-aware fetch. Like get_vcon but:
Accepts an
includearray so you only pay for the parts you need. Valid values are the samesupported_includesreturned byvcon_capabilities.Accepts a
max_response_bytesbudget (default 250 000). If the response would exceed the budget, the call returns{ok: false, error: {code: "RESPONSE_TOO_LARGE"}}rather than truncating silently.Returns the response in the
{ok, item}envelope so the schema matchesdescribe_response_shape("vcon_fetch").
Prefer this over get_vcon from any LLM-driven workflow.
vcon_search
vcon_searchThe contract-aware search. Designed for LLM use:
Modes:
metadata,keyword,semantic,hybrid. Hybrid takes asemantic_weight(0–1) blending the two scores.Cursor-based. Returns
page.next_cursor; the client passes the cursor back to get the next page. No offsets, no page numbers.Dealer filterable. In multi-tenant deployments where Strolid-style dealer attachments are present,
filters.dealer_id(exact match) orfilters.dealer_name(substring) are first-class filters rather than free-form tags. Backed by theaggregate_vcons_by_dealer_statsRPC for fast top-of-funnel counts.Tag-first. Tag filters are the cheapest dimension to filter on; the search pushes them first.
LLM-hardened. Rejects ambiguous queries with a structured error rather than returning bad results — the model can recover from a clean error, but can't recover from a wrong answer it doesn't realize is wrong.
Same include and max_response_bytes controls as vcon_fetch. Same {ok, items, page} envelope.
Recommended flow for an LLM session
Steps 1–4 happen once per session and are cheap. Steps 5–6 are the working loop.
Field-name compatibility
In May 2026 the server also shipped database migration 20251120150100_field_renames.sql that handles the appended → amended and must_support → critical renames at the storage layer (see Field-Name Migration). The contract tools always emit and accept the spec-correct names; the legacy names are translated on read via the vcons_legacy view.
See also
Tool Reference — the full tool list
Field-Name Migration — back-compat behavior
Transport and Deployment — how to actually run a server you can call these tools on
What the vCon MCP Server Can Do — narrative overview
Last updated
Was this helpful?