Cardog

Turn free text into canonical Cardog entity refs — THE text entry point for every other tool. A ref is `{domain}:{key}`, lowercase, with `/` separating composite key segments: "make:tesla", "model:mini/hardtop", "model-year:honda/cr-v/2026", "fuel-type:electric". (Exception: nano/squish keys are uppercase VIN charset — machine-derived, never typed from text.) Every other tool takes refs, never names. Call this FIRST whenever you hold text — "Civic", "2024 Model Y", a misspelling like "teslla" — then reuse the refs for the rest of the session. Returns candidates with confidence, best-first. `best` is the top candidate ONLY when it clears the confidence floor; otherwise it is null and YOU choose from `candidates` (or ask the user) — the API never guesses. Pass `domain` to constrain the search (use domain "model-year" when you need a market_quote instrument). Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Next steps (also echoed in each result's `next` block): search_inventory with make/model refs; market_quote with a model-year: ref; check_recalls with any make/model/model-year ref; dereference a ref (parents, children, counts) at GET /v2/entities/{ref}.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Free text to resolve, e.g. \"2021 Civic\", \"teslla\", \"plug-in hybrid\""
    },
    "domain": {
      "type": "string",
      "description": "Constrain candidates to one domain: \"make\", \"model\", \"model-year\", \"body-style\", \"fuel-type\", \"drive-type\", \"transmission\", \"electrification-level\", \"vehicle-type\". Omit to search across domains."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max candidates (default 5)"
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "query",
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Decode a 17-character VIN into its full Cardog identity: canonical entity refs, the market grains (nano/squish), spec highlights, and links to adjacent resources. VIN ONLY — this tool never fuzzy-matches. If you hold free text ("2021 Civic", a make or model name), do NOT call this: call resolve_entity — free text enters the platform in exactly one tool. A non-VIN input returns a redirect hint, not a decode. A ref is `{domain}:{key}`, lowercase, with `/` separating composite key segments: "make:tesla", "model:mini/hardtop", "model-year:honda/cr-v/2026", "fuel-type:electric". (Exception: nano/squish keys are uppercase VIN charset — machine-derived, never typed from text.) The result's `refs` block (make/model/modelYear/fuelType/…) contains the join keys for every other tool; a null ref means "not derivable for this VIN", never "unknown ref". `squish` (WMI+VDS+year) is always derivable and is a valid market_quote instrument; `nano` is the fungible build grain for dedup/comparables. `specHighlights` is a best-effort skim of the spec sheet (horsepower, economy, range, seating…), each value with its unit; a highlight the trims of the model year do not share is absent. The full sheet lives at GET /v2/specs/{refs.modelYear}. Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Next: check_recalls({ vin }) — recalls listed for the model year; market_quote({ ref: refs.modelYear ?? squish }); search_inventory({ models: [refs.model] }).

{
  "type": "object",
  "properties": {
    "vin": {
      "type": "string",
      "minLength": 1,
      "description": "The 17-character VIN. Free text is NOT accepted here — use resolve_entity for text."
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "vin",
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search live vehicle listings — ref-native. One call returns listings + facets + the total count. The market defaults to Canada, which is the only inventory market today: prices are in each listing's own currency (CAD for Canadian listings) and odometers in km. Filters take entity REFS from resolve_entity / identify_vehicle, never free-text names: makes: ["make:mini"], models: ["model:mini/hardtop"], fuelTypes: ["fuel-type:electric"] — plus year/price/odometer ranges and canonical spec filters, e.g. spec: {"fuelEconomyCombined": {"min": 35}, "heatedSeatsFront": ["standard"]} (numeric attrs take {min,max}; equipment attrs take ["standard"|"optional"|"unavailable"]). A ref is `{domain}:{key}`, lowercase, with `/` separating composite key segments: "make:tesla", "model:mini/hardtop", "model-year:honda/cr-v/2026", "fuel-type:electric". (Exception: nano/squish keys are uppercase VIN charset — machine-derived, never typed from text.) Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. A typo'd or unknown ref 400s with code "unknown_entity_refs" naming it, with nearest-ref suggestions — correct the ref (usually via resolve_entity) and retry. Facets in the result are (ref, name, count) buckets over the MATCHING set — they double as the valid filter vocabulary for your next, narrower call. Every listing row carries its refs (makeRef/modelRef/nano). Next: market_quote({ ref: "model-year:…" }) for pricing context; check_recalls({ vin }) per listing; GET /v2/listings/vin/{vin} for the full canonical spec.

{
  "type": "object",
  "properties": {
    "makes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"make\" domain, e.g. [\"make:mini\"]"
    },
    "models": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"model\" domain, e.g. [\"model:mini/hardtop\"]"
    },
    "bodyStyles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"body-style\" domain, e.g. [\"body-style:sport-utility-vehicle-suv\"]"
    },
    "fuelTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"fuel-type\" domain, e.g. [\"fuel-type:electric\"]"
    },
    "driveTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"drive-type\" domain, e.g. [\"drive-type:awd-all-wheel-drive\"]"
    },
    "transmissions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"transmission\" domain, e.g. [\"transmission:automatic\"]"
    },
    "electrificationLevels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"electrification-level\" domain, e.g. [\"electrification-level:bev-battery-electric-vehicle\"]"
    },
    "vehicleTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"vehicle-type\" domain, e.g. [\"vehicle-type:passenger-car\"]"
    },
    "nanos": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entity refs in the \"nano\" domain, e.g. [\"nano:5TDGSKFCRS\"]"
    },
    "year": {
      "type": "object",
      "properties": {
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        }
      },
      "additionalProperties": false,
      "description": "Model year range"
    },
    "price": {
      "type": "object",
      "properties": {
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        }
      },
      "additionalProperties": false,
      "description": "Price, in the listing currency (CAD in the default Canadian market) range"
    },
    "odometer": {
      "type": "object",
      "properties": {
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        }
      },
      "additionalProperties": false,
      "description": "Odometer, in km range"
    },
    "spec": {
      "type": "object",
      "additionalProperties": {},
      "description": "Canonical spec filters keyed by SpecAttributeId: numeric → {\"min\",\"max\"}, equipment → [\"standard\"|\"optional\"|\"unavailable\"]. Example: {\"fuelEconomyCombined\": {\"min\": 35}, \"heatedSeatsFront\": [\"standard\"]}. Bare scalars are invalid — \"standard\" must be [\"standard\"]; a wrong-shaped value errors with code \"invalid_spec_filter\". Unknown keys 400 with code \"unknown_spec_attributes\"."
    },
    "sort": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string",
          "enum": [
            "price",
            "year",
            "odometer",
            "createdAt",
            "score"
          ]
        },
        "direction": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        }
      },
      "additionalProperties": false
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Page number (default 1)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Rows per page (default 10, max 50)"
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The live market card for one instrument: quote (live listing count, best/p25/median/p75 price, average days-on-market, 30-day price cuts), a daily-bar history summary, and a bounded sample of the live listings behind the numbers. `ref` must be an INSTRUMENT ref — one of two grains: - "model-year:{make}/{model}/{year}" (e.g. "model-year:honda/cr-v/2026") — lowercase, /-separated; get it from resolve_entity (domain "model-year") or identify_vehicle's refs.modelYear. - "squish:{9 uppercase VIN chars}" (e.g. "squish:5TDGSKFCS") — the exact-config grain; get it from identify_vehicle. (squish/nano keys are the ONLY uppercase refs; every other domain is lowercase.) No other ref domain quotes. Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Optional `window` picks the history span: 1w, 1m, 3m, 6m, ytd, 1y, 3y, 5y, 10y, all. Next: search_inventory with the model's refs to walk the full book; check_recalls({ ref }) on a model-year ref; GET /v2/tape/history/{ref} for every daily bar.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "minLength": 1,
      "description": "Instrument ref: \"model-year:honda/cr-v/2026\" or \"squish:5TDGSKFCS\". Free text never quotes — resolve_entity first."
    },
    "window": {
      "type": "string",
      "enum": [
        "1w",
        "1m",
        "3m",
        "6m",
        "ytd",
        "1y",
        "3y",
        "5y",
        "10y",
        "all"
      ],
      "description": "History window (server default when omitted)"
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "ref",
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Recall campaigns LISTED for a vehicle's model year in its market of sale, ref-keyed, one record per authority, never merged. Default market CA: Transport Canada safety recalls and ECCC emissions notices (each row carries `regime`; never call an emissions notice a safety recall). Pass `market` when the user's market is known (US, AU, …), `include_other: true` to see other markets' records (NHTSA for a Canadian car) uncounted, `authority` to pick authorities. This is a possible-recall list, not a VIN-level determination: campaigns match by model year, not by the campaign's VIN range, and Cardog does not see remedy status. Every result carries `applicability: "listed_for_model_year"`. When you tell a user about these, say they MAY apply and that the manufacturer's own VIN recall lookup (in Canada) or a dealer confirms; never say "open", "outstanding" or "critical", and never say "no recalls" as a clearance. Compliance guide: https://cardog.app/docs/compliance. Pass EXACTLY ONE of: - `vin` (17 characters) — resolves the VIN to its model year, then lists that model year's campaigns. In the result, `resolved: false` means the VIN is not bridged into the graph yet; `resolved: true, total: 0` means none are listed for the model year (not that the vehicle is clear). - `ref` — an entity ref scoping campaigns: "make:honda", "model:honda/cr-v", or "model-year:honda/cr-v/2026". A ref is `{domain}:{key}`, lowercase, with `/` separating composite key segments: "make:tesla", "model:mini/hardtop", "model-year:honda/cr-v/2026", "fuel-type:electric". (Exception: nano/squish keys are uppercase VIN charset — machine-derived, never typed from text.) Get refs from resolve_entity or identify_vehicle — never construct them from guessed names. Each campaign carries: authority (tc, eccc, nhtsa, au, …), market and regime + campaign number, component, defect/consequence summaries, the corrective action, recall date, units affected, and `affects` — the affected model-years as refs. `asOf` (VIN checks) is when the recall data was last updated, citable. Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Next: identify_vehicle({ vin }) for the vehicle's full identity; market_quote({ ref: "model-year:…" }); GET /v2/recalls/{recall-ref} for one campaign; GET /v2/recalls/feed for the newest campaigns.

{
  "type": "object",
  "properties": {
    "vin": {
      "type": "string",
      "description": "17-character VIN — resolved to its model year; campaigns listed for that model year are returned. Exclusive with `ref`."
    },
    "ref": {
      "type": "string",
      "description": "Entity ref scope: \"make:honda\", \"model:honda/cr-v\", or \"model-year:honda/cr-v/2026\". Exclusive with `vin`."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max campaigns for a ref-scoped query (default 25, max 100)"
    },
    "market": {
      "type": "string",
      "enum": [
        "CA",
        "US",
        "AU",
        "GB",
        "JP",
        "KR",
        "CN",
        "IL",
        "all"
      ],
      "description": "Where the vehicle was sold. Default CA (Transport Canada recalls and ECCC emissions notices). Pass the user's market when known; never guess it from the VIN."
    },
    "authority": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Authority codes to pick, e.g. [\"nhtsa\"]. Without `market`, picks across every market."
    },
    "regime": {
      "type": "string",
      "enum": [
        "safety",
        "emissions",
        "all"
      ],
      "description": "`safety` recalls, `emissions` notices, or `all` (default)."
    },
    "include_other": {
      "type": "boolean",
      "description": "Also return `otherRecalls`: the records of other markets (e.g. NHTSA for a Canadian car), never counted."
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The factory window sticker (Monroney label) we hold for a VIN, or why there is none. Guide: https://cardog.app/docs/window-sticker. Pass `vin` (17 characters). The result has exactly one of: - `label` — we hold the manufacturer's label: `issuer`, `retrievedAt`, `vinVerified` (true only when the VIN was read inside the file; false means the manufacturer's service returned it for this VIN and nothing stronger), and `document` (a stable identifier + SHA-256, and `downloadUrl`: a signed link to the PDF, good for 24 hours, free, no API key needed. You may give it to a person as a clickable link. Do not store the link: call this tool again for a fresh one, which bills the label again. `sha256` identifies the file). Costs 5 credits. - `unavailable` — no label, and `reason` says why. `not_yet_harvested` is the ONLY reason worth retrying later. `no_lane` (not collected for this manufacturer), `lane_us_only` (US-sold vehicles only), `issuer_has_no_record` (the manufacturer has none) and `pre_lane_model_year` (predates our coverage) are final. Costs 0 credits. Absence is a normal answer, not an error. The label's printed contents (options, MSRP, fuel economy) are not served yet. Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Next: identify_vehicle({ vin }) for the vehicle's identity and its refs (model-year:… for market_quote); check_recalls({ vin }) for campaigns listed for the model year.

{
  "type": "object",
  "properties": {
    "vin": {
      "type": "string",
      "description": "17-character VIN"
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "vin",
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Every motor carrier a commercial vehicle was observed running under, from the US federal roadside record. Guide: https://cardog.app/docs/carriers. Pass `vin` (17 characters). The result is one item per day a roadside inspection or crash report put a carrier on the unit, most recent first. Each item has `observedAt`, `source` and `value` (`dotNumber`, and `ref` in the `{domain}:{key}` grammar every Cardog ref uses: `org:usdot/{dotNumber}`). The tool always asks for `detail` (which record it was, an inspection or a crash, and the carrier as it stands on the register: legal name, domicile, declared power units). These are observed associations on dated records, not ownership: a leased unit is run by a carrier that does not own it. Covers the power unit (tractor or straight truck). A trailer's carriers come from carrier_lookup({ q: vin }). A consumer car returns no items; that is not evidence of anything. Costs 3 credits when there is at least one item, 0 when there is none. Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Next: carrier_lookup({ q: "<dotNumber>" }) for the carrier and everything else it ran; identify_vehicle({ vin }) for what the unit is.

{
  "type": "object",
  "properties": {
    "vin": {
      "type": "string",
      "description": "17-character VIN"
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "vin",
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Find a motor carrier and read its record: name → US DOT number → every unit observed under it. Guide: https://cardog.app/docs/carriers. Pass `q`: a carrier name or part of one ("bison transport"), a US DOT number ("245330"), or a 17-character VIN (the carriers that unit was observed under). Optional `state` and `country` (two letters) narrow a name match; `limit` caps matches (default 5, max 50). The result lists matches, best first, each with `dotNumber`, `legalName`, `dbaName`, `domicile` (city, state, country), `operation` and declared `powerUnits`. When exactly one carrier matches, or `q` was a DOT number, the result also carries `carrier`: the full read with `declared` (what it filed about itself, dated by `filedOn`, self-reported) and `observed` (what roadside inspections and crash reports recorded: distinct units, inspections, crashes, first and last seen). Declared and observed never mix. The carrier's ref is `org:usdot/{dotNumber}`, the `{domain}:{key}` grammar every Cardog ref uses. Pass `vehicles: true` to also return the first page of units observed under that carrier, most recently seen first, each with a link to every carrier it ran under. A DOT number the road record names but the register does not still reads: `legalName` and every `declared` field null, `observed` filled. COVERAGE: the US federal register and roadside record: US DOT-regulated carriers, including Canadian and Mexican carriers that cross the border. A fleet that only runs inside one province is absent. Fleet rows are observed associations on dated rows, not a confirmed current fleet and not ownership. COST: the tool chains the calls. The search is 1 credit. When it narrows to one carrier (a DOT number, or exactly one name match) the tool also reads the carrier, 5 more, so that call is 6; with `vehicles: true` it also fetches the first fleet page, 5 more, so up to 11. A name search with several matches is 1. Errors are instructions: every failure returns {code, message, hint, suggestions} — follow `hint` for the next call; `suggestions` lists nearest valid refs for a bad ref. Unknown-but-well-formed refs are a 400 naming the ref, NEVER a silent fuzzy match. Next: vehicle_operators({ vin }) for every carrier a unit in the fleet ran under.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Carrier name, US DOT number, or 17-character VIN"
    },
    "state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "State or province, two letters"
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "US, CA or MX"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Match cap, default 5"
    },
    "vehicles": {
      "type": "boolean",
      "description": "Also return the first page of units under the one matched carrier"
    },
    "context": {
      "type": "string",
      "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\""
    }
  },
  "required": [
    "q",
    "context"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}