--- title: "Mcp Resolve Description" method: POST path: "/api/v1/mcp/resolve-description" tags: ["mcp"] --- # Mcp Resolve Description `POST /api/v1/mcp/resolve-description` ## Request - Base URL: `https://api.civilquants.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.civilquants.com/api/v1/mcp/resolve-description` - Auth: none declared Deterministic catalogue router (item L). Free / anonymous-allowed. ## Headers - `authorization` string, nullable ## Request body - ResolveRequest: Request body for POST /api/v1/mcp/resolve-description (item L). - `description` string, required - `preferred_standard` 'CESMM4' | 'NRM2' | 'SMM7' | 'MMHW', nullable - `return_resolution_log` boolean ## Response `200` Successful Response - union - MCPResponseResolveResult - `data` ResolveResult: The typed payload wrapped in MCPResponse[ResolveResult]. - `query` string, required - `preferred_standard` 'CESMM4' | 'NRM2' | 'SMM7' | 'MMHW', nullable - `candidates` ResolvedAssembly[] - `slug` string, required - `display_name` string, required - `tier` 'free' | 'paid', required - `category_l1` string, required - `category_l2` string, required - `compute_tool` string, required - `supports_multi_section` boolean - `multi_section_tool` string, nullable - `standard_note` string, nullable - `free_alternative` string, nullable - `fields` FieldSpec[] - `name` string, required - `label` string, required - `default` union, required - number - integer - string - boolean - `group` string, required - `unit` string, nullable - `min` number, nullable - `max` number, nullable - `help_text` string, nullable - `is_run_length` boolean - `load_bearing` boolean - `suggested_params` SuggestedParam[] - `name` string, required - `value` number, required - `unit` string, nullable - `source` string, required - `confidence` 'high' | 'medium' | 'low', required - `questions` string[] - `resolution_log` MatchTrace[], nullable - `slug` string, required - `score` number, required - `matched_terms` string[] - `error` ErrorEnvelope: Canonical schema § 0.4 — error payload returned in `MCPResponse.error`. - `code` 'RATE_LIMIT_EXCEEDED' | 'TIER_INSUFFICIENT' | 'INVALID_INPUT' | 'SCHEMA_VERSION_MISMATCH' | 'SCHEMA_INVARIANT_VIOLATION' | 'UPSTREAM_TIMEOUT' | 'BACKEND_FAILURE' | 'IP_BLOCKED' | 'RESOURCE_NOT_FOUND' | 'RENDER_FAILURE' | 'OCR_LOW_CONFIDENCE' | 'MANUAL_REVIEW_REQUIRED' | 'ACCEPTANCE_REQUIRED' | 'INVALID_TOKEN', required: Canonical schema § 0.5 catalogue. Each member maps to a documented `recoverable` flag (see `IS_RECOVERABLE`) — clients use the flag to decide retry vs surface. - `message` string, required - `recoverable` boolean, required - `retry_after_seconds` integer, nullable - `details` object, nullable - `_meta` ResponseMeta, required: Canonical schema § 0.2 — present on every MCPResponse. Required fields: `schema_version`, `request_id`, `issued_at`, `tier`. The free-tier-only fields (`upgrade_hint`, `tos_url`, `warranty_disclaimer`, `tier_upgrade`, `rate_limit_remaining`) are populated by the middleware when `tier == "free"`; absent on paid-tier responses. - `schema_version` '1.0.0' - `request_id` string, required - `issued_at` string, required - `tier` 'free' | 'paid', required - `document_id` string, nullable - `deliverables` DeliverableURLs: Canonical schema § 0.3 — R2 signed URLs (24h TTL). - `pdf_url` string, nullable - `xlsx_url` string, nullable - `dxf_url` string, nullable - `docx_url` string, nullable - `expires_at` string, required - `rate_limit_remaining` integer, nullable - `upgrade_hint` string, nullable - `tos_url` string, nullable - `warranty_disclaimer` string, nullable - `scope_boundary` ScopeBoundary: Canonical schema § 0.6 — surfaces what this assembly produces vs not. - `produced` string[], required - `not_in_scope` string[], required - `recommended_companions` string[], nullable - `tier_upgrade` TierUpgrade: Canonical schema § 0.7 — present on free-tier responses only. - `current_tier` 'free' - `available_tiers` TierOption[], required - `tier_slug` '7_day_pass' | 'solo' | 'studio' | 'practice', required - `display_name` string, required - `price_local` number, required - `currency` 'GBP' | 'SGD' | 'EUR' | 'USD' | 'CAD' | 'AUD' | 'NZD' | 'MYR', required - `billing` 'one_off' | 'monthly' | 'annual', required - `unlock_summary` string, required - `pricing_url` string - `pass_credit` PassCreditOffer: Canonical schema § 0.7 — pass-credit upgrade hook. - `amount_local` number, required - `currency` string, required - `redeemable_until` string, required - `applies_to` 'solo_first_month' - `hint` string, nullable - `output_mode` OutputModeInfo: Surfaces what a trimmed ``output_mode`` withheld from ``data``. A trimmed mode (``summary`` / ``material_schedule`` / ``boq`` / ``boq_with_backup``) withholds already-computed fields to keep the chat payload small. The withheld value reads to a client agent as "capability missing" (the box-culvert "geometry builder isn't firing" scare) rather than "pared for size": ``drawing`` and ``audit_trail`` appear as ``null``, ``boq_rows`` as an empty list ``[]`` (its type forbids ``null``) — both indistinguishable from a genuine absent result. This names the withheld fields and the exact mode that brings each back, so the value is unambiguous. Absent on the default ``full_json`` mode — nothing is withheld, nothing to point at. - `mode` 'summary' | 'material_schedule' | 'boq' | 'boq_with_backup', required - `omitted_fields` string[], required - `retrieve_with` string, required - MCPResponseAny - `data` unknown - `error` ErrorEnvelope: Canonical schema § 0.4 — error payload returned in `MCPResponse.error`. - `code` 'RATE_LIMIT_EXCEEDED' | 'TIER_INSUFFICIENT' | 'INVALID_INPUT' | 'SCHEMA_VERSION_MISMATCH' | 'SCHEMA_INVARIANT_VIOLATION' | 'UPSTREAM_TIMEOUT' | 'BACKEND_FAILURE' | 'IP_BLOCKED' | 'RESOURCE_NOT_FOUND' | 'RENDER_FAILURE' | 'OCR_LOW_CONFIDENCE' | 'MANUAL_REVIEW_REQUIRED' | 'ACCEPTANCE_REQUIRED' | 'INVALID_TOKEN', required: Canonical schema § 0.5 catalogue. Each member maps to a documented `recoverable` flag (see `IS_RECOVERABLE`) — clients use the flag to decide retry vs surface. - `message` string, required - `recoverable` boolean, required - `retry_after_seconds` integer, nullable - `details` object, nullable - `_meta` ResponseMeta, required: Canonical schema § 0.2 — present on every MCPResponse. Required fields: `schema_version`, `request_id`, `issued_at`, `tier`. The free-tier-only fields (`upgrade_hint`, `tos_url`, `warranty_disclaimer`, `tier_upgrade`, `rate_limit_remaining`) are populated by the middleware when `tier == "free"`; absent on paid-tier responses. - `schema_version` '1.0.0' - `request_id` string, required - `issued_at` string, required - `tier` 'free' | 'paid', required - `document_id` string, nullable - `deliverables` DeliverableURLs: Canonical schema § 0.3 — R2 signed URLs (24h TTL). - `pdf_url` string, nullable - `xlsx_url` string, nullable - `dxf_url` string, nullable - `docx_url` string, nullable - `expires_at` string, required - `rate_limit_remaining` integer, nullable - `upgrade_hint` string, nullable - `tos_url` string, nullable - `warranty_disclaimer` string, nullable - `scope_boundary` ScopeBoundary: Canonical schema § 0.6 — surfaces what this assembly produces vs not. - `produced` string[], required - `not_in_scope` string[], required - `recommended_companions` string[], nullable - `tier_upgrade` TierUpgrade: Canonical schema § 0.7 — present on free-tier responses only. - `current_tier` 'free' - `available_tiers` TierOption[], required - `tier_slug` '7_day_pass' | 'solo' | 'studio' | 'practice', required - `display_name` string, required - `price_local` number, required - `currency` 'GBP' | 'SGD' | 'EUR' | 'USD' | 'CAD' | 'AUD' | 'NZD' | 'MYR', required - `billing` 'one_off' | 'monthly' | 'annual', required - `unlock_summary` string, required - `pricing_url` string - `pass_credit` PassCreditOffer: Canonical schema § 0.7 — pass-credit upgrade hook. - `amount_local` number, required - `currency` string, required - `redeemable_until` string, required - `applies_to` 'solo_first_month' - `hint` string, nullable - `output_mode` OutputModeInfo: Surfaces what a trimmed ``output_mode`` withheld from ``data``. A trimmed mode (``summary`` / ``material_schedule`` / ``boq`` / ``boq_with_backup``) withholds already-computed fields to keep the chat payload small. The withheld value reads to a client agent as "capability missing" (the box-culvert "geometry builder isn't firing" scare) rather than "pared for size": ``drawing`` and ``audit_trail`` appear as ``null``, ``boq_rows`` as an empty list ``[]`` (its type forbids ``null``) — both indistinguishable from a genuine absent result. This names the withheld fields and the exact mode that brings each back, so the value is unambiguous. Absent on the default ``full_json`` mode — nothing is withheld, nothing to point at. - `mode` 'summary' | 'material_schedule' | 'boq' | 'boq_with_backup', required - `omitted_fields` string[], required - `retrieve_with` string, required ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/civilquants/apis/civilquants-api.md) · [All operations](https://skmtc.dev/civilquants/apis/civilquants-api/llms.txt) · [OpenAPI document](https://skmtc.dev/civilquants/apis/civilquants-api/revisions/84569a3761e1?raw)