선별된 NHTSA vPIC 데이터베이스에서 VIN을 디코딩하고 차량 데이터를 조회하세요 — Model Context Protocol 기반.
LLM이 NHTSA의 vPIC 데이터를 사용하여 차량 식별 번호(VIN)를 디코딩하고 제조사, 모델, 차량 제원을 조회할 수 있는 독립형 오프라인 지원 MCP 서버입니다.
pip install vin-decode-mcp
vin-decode-mcp # Start the MCP server오프라인: 인터넷 연결 없이 작동합니다. 선별된 SQLite 데이터베이스(~4.5 MB)는 자체 포함되어 있습니다.
속도 제한 없음: vPIC API를 직접 호출하는 것과 달리 로컬 쿼리는 무제한입니다.
빠름: SQLite 데이터베이스에 대한 패턴 매칭은 마이크로초 단위로 완료됩니다.
LLM 네이티브: 풍부한 docstring, 스키마 리소스, 구조화된 JSON 출력을 제공하는 도구입니다.
오픈 데이터: NHTSA vPIC는 미국 정부의 오픈 데이터로, 무료이며 API 키가 필요 없습니다.
Related MCP server: VIN MCP
미국 시장 차량, 모델 연도 1981년 이후
534개 제조사, 9,175개 모델, 88,140개 VIN 패턴
승용차, 트럭, MPV, 오토바이, 오프로드 차량
제외: 버스, 트레일러, 저속 차량, 미완성 차량
제원 정보만 포함 — 이 데이터베이스에는 소유권, 사고, 주행거리계, 또는 도난 이력이 포함되지 않습니다(이러한 정보는 NMVTIS/상용 데이터 소스가 필요).
pip install vin-decode-mcp또는 소스에서:
git clone https://github.com/<org>/vin-decode-mcp.git
cd vin-decode-mcp
pip install -e .# Default: stdio transport (for Claude Desktop, Cursor, etc.)
vin-decode-mcp
# HTTP transport
vin-decode-mcp --transport http --port 8765다음 파일에 추가하세요: ~/.config/claude-desktop/config.json (macOS에서는 ~/Library/Application Support/claude-desktop/config.json)
{
"mcpServers": {
"vin-decode": {
"command": "vin-decode-mcp"
}
}
}Claude Desktop을 다시 시작하세요. 이제 모델이 대화에서 VIN 디코딩 도구를 사용할 수 있습니다.
도구 | 설명 |
| VIN을 디코딩 → 제조사, 모델, 연도, 차량 유형 |
|
|
| 모든 차량 제조사 나열 |
| 특정 제조사의 모델 나열 |
| 생산 연도 범위 가져오기 |
| WMI를 디코딩 → 제조사 정보 |
| 사용 가능한 차량 유형 나열 |
| 특정 제조사의 차량 유형 나열 |
>>> decode_vin("1HGCM82633A004352")
{
"vin": "1HGCM82633A004352",
"make": "Honda",
"model": "Accord",
"year": 2003,
"vehicle_type": "Passenger Car",
"wmi": "1HG",
"confidence": "full"
}
>>> get_model_years("Porsche", "911")
{"year_from": 1981, "year_to": null}
>>> decode_partial_vin("5UXWX7C5*BA")
[{"make": "BMW", "model": "X5", "year": 2011, "confidence": "partial_match"}]컴파일된 데이터베이스는 Hugging Face에서 호스팅됩니다:
데이터셋: https://huggingface.co/datasets/vin-decode-mcp/vpic-database 직접 다운로드: https://huggingface.co/datasets/vin-decode-mcp/vpic-database/resolve/main/vpic_decode.db
# Set via environment variable
export VIN_MCP_DB_PATH=/path/to/vpic_decode.db
vin-decode-mcp
# Or via CLI flag
vin-decode-mcp --db-path /path/to/vpic_decode.db데이터베이스는 NHTSA의 독립형 PostgreSQL 데이터베이스에서 약 6~12개월마다 다시 빌드됩니다:
# Requires PostgreSQL installed (pg_restore, psql)
bash tools/rebuild.sh
# Or step by step:
# 1. Download NHTSA data: https://vpic.nhtsa.dot.gov/Downloads/
# 2. Convert to SQLite
python3 tools/convert_to_sqlite.py --input dump.sql --output vpic_lite.db
# 3. Build curated database
python3 tools/build_db.py --source vpic_lite.db --output vpic_decode.dbHugging Face 설정 지침은 docs/hf-setup.md를 참조하세요.
차량 데이터는 NHTSA의 vPIC — 미국 고속도로교통안전청(National Highway Traffic Safety Administration)의 Vehicle Product Information Catalog 및 Vehicle Listing에서 가져온 것입니다. NHTSA는 미국 정부 기관입니다.
데이터 라이선스: 미국 정부 저작물(공개 도메인)
API: 키 또는 등록 불필요
갱신 주기: ~6-12개월
오류 신고: manufacturerinfo@dot.gov 또는 1-888-399-3277로 NHTSA Manufacturer Helpdesk에 문의하세요.
User / LLM Agent
│
▼ MCP (stdio / HTTP)
┌──────────────────┐
│ vin-decode-mcp │ pip install vin-decode-mcp
│ (FastMCP server)│ env: VIN_MCP_DB_PATH=/path/to/vpic_decode.db
└────────┬─────────┘
│ sqlite3 (mode=ro)
▼
┌──────────────────┐
│ vpic_decode.db │ ~4.5 MB, curated
│ (Hugging Face) │ makes + models + WMI + VIN patterns
└──────────────────┘
▲
│ rebuilds from
┌──────────────────┐
│ NHTSA vPIC PG DB │ 69 MB, official
│ (NHTSA website) │ refreshed 2x/year
└──────────────────┘vin-decode-mcp/
├── src/vin_decode_mcp/
│ ├── __init__.py # Package init
│ ├── server.py # FastMCP server with all tools
│ ├── database.py # SQLite layer + VIN decoder
│ └── cli.py # CLI entry point
├── tools/
│ ├── build_db.py # Pipeline orchestrator
│ ├── convert_to_sqlite.py # PG → SQLite converter
│ ├── rebuild.sh # Full rebuild script
│ ├── build_db.py # Curated DB builder (orchestrator for the pipeline)
│ ├── curation.json # Make/model curation rules
│ ├── overlay.json # Grey-import classic additions
│ └── README.md # Rebuild instructions
├── tests/
│ ├── conftest.py # Test fixtures
│ ├── test_decode.py # VIN decode canary tests
│ ├── test_server.py # Bulk lookup tests
│ └── fixtures/
│ ├── build_test_db.py # Test database builder
│ └── test_vpic.db # Minimal test database
├── .github/workflows/
│ ├── ci.yml # CI: test + lint
│ └── rebuild-db.yml # Scheduled DB rebuild
├── docs/
│ └── hf-setup.md # Hugging Face setup guide
├── pyproject.toml
├── LICENSE
├── README.md
└── vpic_pare_down.py # Pare-down pipeline (original)# Install dev dependencies
pip install -e ".[dev]"
# Run tests
python -m pytest tests/ -v
# Lint
python -m ruff check src/ tests/
# Format
python -m ruff format src/ tests/vin-decode-mcp | NHTSA vPIC API | vin-mcp (NLMA) | |
전송 방식 | 로컬 SQLite | HTTP REST | HTTP REST |
오프라인 | ✅ | ❌ | ❌ |
속도 제한 | 아니요 | 예 | 예 |
데이터 크기 | ~4.5 MB | 해당 없음 | 해당 없음 |
VIN 필드 | 제조사 + 모델 + 연도 | ~130개 필드 | ~130개 필드 |
제조사/모델 | ✅ 534/9,175 | ✅ 전체 카탈로그 | ✅ 전체 카탈로그 |
설치 |
| 없음 |
|
MIT License — 코드는 MIT, 데이터는 미국 정부 공개 도메인입니다.
자세한 내용은 LICENSE를 참조하세요.
기여를 환영합니다! 다음을 따라주세요:
Fork하고 기능 브랜치를 만드세요.
새 기능에 대한 테스트를 추가하세요.
CI가 통과하는지 확인하세요.
풀 리퀘스트를 제출하세요.
주요 변경 사항이 있다면 먼저 이슈를 열어 접근 방식을 논의하세요.
Decode a partial VIN pattern with wildcards.
Supports * as a wildcard for exactly one character (matching the vPIC pattern format). Useful for matching a VIN you don't have the full 17 characters of, or for pattern-based lookups.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 20). | |
| pattern | Yes | Partial VIN with * wildcards (e.g. "5UXWX7C5*BA"). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden and does well by explaining that * matches exactly one character and that it follows the vPIC pattern format. It does not discuss edge cases, errors, or authorization, but the operation is a read-only decode, and the output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded: the first sentence states the core purpose, and the second adds wildcard semantics and use cases. Every sentence contributes useful information without redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema and fully documented parameters, the description is nearly complete. It explains when to use the tool and the wildcard behavior, though it could be slightly more explicit about how this differs from decoding a full VIN.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by specifying that the wildcard matches exactly one character and that the format aligns with vPIC. This clarifies pattern semantics beyond the schema's brief example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it decodes partial VIN patterns with wildcards, using a specific verb and resource. It differentiates from sibling decode_vin by emphasizing partial patterns and wildcard matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says the tool is useful when you don't have the full 17-character VIN or need pattern-based lookups. It does not explicitly name decode_vin as the alternative for full VINs, but the context makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode a VIN to make, model, year, and vehicle type.
Returns the decoded make, model, model year, and vehicle type for a 17-character VIN. Uses the NHTSA vPIC pattern database for make/model resolution. Model year is computed from VIN position 10 unless you provide model_year explicitly.
Partial VINs (shorter than 17 characters) may still decode if the WMI (positions 1-3) matches a known manufacturer.
| Name | Required | Description | Default |
|---|---|---|---|
| vin | Yes | Vehicle Identification Number (17 chars, or shorter for partial). | |
| model_year | No | Optional explicit model year to improve decode accuracy. If omitted, computed from VIN position 10 + position 7. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose useful context: use of the NHTSA vPIC database, model-year derivation from VIN position 10, and the WMI condition for partial VINs. It is slightly inaccurate because the schema says model year is computed from position 10 plus position 7, while the description omits position 7.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs move from purpose to return details to edge-case behavior, with the core action front-loaded. The return list in the first and second sentences is slightly redundant ('make, model, year' vs 'make, model, model year'), but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavior, data source, and partial-VIN edge case, and an output schema exists for return values. The major missing context is how this tool relates to decode_partial_vin, which is a sibling that appears to overlap, leaving the agent with no basis for choosing between them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the model_year override behavior ('unless you provide model_year explicitly') and by specifying the WMI positions relevant for partial decoding, though the model-year formula inconsistency slightly qualifies the added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Decode a VIN to make, model, year, and vehicle type' states a specific verb and resource, and the second paragraph names concrete outputs. However, it does not distinguish itself from sibling decode_partial_vin, and its partial-VIN caveat actually blurs the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool over decode_partial_vin or when to avoid it. The statement that partial VINs may decode provides input tolerance, but not a decision rule; an agent cannot tell which decode tool to choose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all vehicle makes registered in vPIC.
Returns every make currently in the curated database. This includes makes from all vehicle types (cars, trucks, motorcycles, etc.) that passed the curation filter.
Returns: List of dicts with keys: id, name. Sorted alphabetically by name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It explains the curation filter, that all vehicle types are included, the exact return shape (list of dicts with id and name), and alphabetical sorting — substantial transparency for a listing endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then scopes the data ('all vehicle types', 'curation filter'), and finishes with a precise return contract. The only minor overlap is between 'registered in vPIC' and 'curated database,' but both add distinct context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list endpoint, the description is complete: it states what data is returned, the inclusion criteria, the output structure, and ordering. The presence of an output schema further covers return details, and no behavior needed to invoke the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema already covers 100% of properties, so the baseline is 4. The description adds no parameter syntax, which is appropriate because no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List all vehicle makes registered in vPIC.' It reinforces the scope with 'every make currently in the curated database' and the return structure, making it easy to distinguish from siblings like get_models_for_make or decode_vin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's zero-parameter, all-makes purpose makes its usage context clear, but the description does not explicitly name alternatives or give when-not-to-use guidance. Since siblings are all more specific (decoding VINs, model lookups), the intended use is still evident without exclusion statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vehicle types a given make produces.
Useful for understanding what categories a manufacturer covers (e.g. BMW produces "Motorcycle", "Passenger Car", "Truck").
| Name | Required | Description | Default |
|---|---|---|---|
| make | Yes | Make name (e.g. "BMW"). Case-insensitive. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. It clearly indicates a read-only listing behavior, but it does not state how unknown makes are handled, whether results are sorted, or whether any special permissions are required. For a simple query tool this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the core operation and follow with a concrete useful example. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup with an output schema, the description covers purpose and an example. It does not address the boundary with the sibling get_vehicle_types, which would be useful for disambiguation, but the tool is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the make parameter is documented with type, example, and case-insensitivity. The tool description adds only a contextual example, so it does not meaningfully extend the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific operation ('List') and resource ('vehicle types a given make produces'), which clearly distinguishes it from siblings like get_all_makes and get_models_for_make. The BMW example reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence explicitly frames the appropriate use case: understanding what categories a manufacturer covers. It does not enumerate exclusions or name alternative tools, but the context is clear enough for the common case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all models for a given make.
Optionally filter by vehicle type to narrow results (e.g. get only car models or only motorcycle models for a make that produces both).
| Name | Required | Description | Default |
|---|---|---|---|
| make | Yes | Make name (e.g. "Honda"). Case-insensitive. Use get_all_makes() to list valid names; numeric make IDs are not accepted here. | |
| vehicle_type | No | Optional vehicle type filter ("Passenger Car", "Motorcycle", "Truck", etc.). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the behavioral burden. The verb 'List' transparently signals a read-only operation, and the description states the optional narrowing behavior with a concrete example. It does not go into error cases or edge behavior, but for a simple look-up tool the core behavior is adequately disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loading the main purpose and then clarifying the optional filter with an example. Every sentence contributes; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple 2-parameter shape, complete schema descriptions, and presence of an output schema, the description covers what an agent needs for a correct call. The only minor gap is the absence of explicit routing guidance among siblings, but that is not essential for this tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds value by explaining that vehicle_type narrows the result set and by giving the car-versus-motorcycle example, reinforcing the parameter's intended effect. It doesn't add new details about the make parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear directive: 'List all models for a given make.' This names the exact verb, resource, and scope, and the optional vehicle_type filter explains the only variant. It is easy to distinguish from siblings such as get_all_makes or get_model_years because the tool's target resource is explicitly 'models'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes the obvious use case—retrieving models for a specified make—and the optional filtering context. However, it never explicitly says when to prefer this over sibling lookup tools or when not to use it, leaving tool selection to inference from the names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the model year range for a make/model pair.
| Name | Required | Description | Default |
|---|---|---|---|
| make | Yes | Make name (e.g. "Porsche"). Case-insensitive. | |
| model | Yes | Model name (e.g. "911"). Case-insensitive. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Get the model year range' indicates a read-only lookup and gives a hint about the output shape, but it does not disclose edge cases such as unsupported make/model pairs or empty results. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant wording. The action, resource, and scope are all present and front-loaded, which is appropriate for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple two-required-parameter lookup, full schema descriptions, and an existing output schema, the description is mostly sufficient for an agent to select and call the tool. It lacks explicit sibling routing, but the tool's straightforward shape makes the overall definition adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the two parameters, including examples and case-insensitivity notes. The description adds only the general notion of a make/model pair, so it does not meaningfully go beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get') and a distinct resource ('model year range') scoped to a make/model pair, which differentiates it from sibling tools like get_all_makes and get_models_for_make. However, it does not explicitly name or exclude any sibling, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'for a make/model pair' qualifier implies the intended use case, and the required parameters reinforce it. But the description gives no explicit when-to-use vs alternatives guidance, no exclusions, and no mention of related tools like get_models_for_make when only a make is known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available vehicle types.
Returns the vehicle types in the curated dataset (e.g. Passenger Car, Motorcycle, Truck, MPV, Off-Road Vehicle).
Returns: List of dicts with keys: id, name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It clearly indicates this is a read-only listing operation and discloses the return shape as a list of dicts with keys 'id' and 'name', plus representative values. It could mention sorting or deterministic ordering, but for a zero-parameter lookup this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary action. There is minor redundancy between 'List all available vehicle types' and 'Returns the vehicle types in the curated dataset', but the examples and explicit return keys make the extra text worthwhile.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list endpoint, the description is complete: it states the scope, gives example values, and specifies the output structure. The only notable gap is not addressing the similar sibling get_make_vehicle_types, but that is more of a usage-guidance concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description cannot add parameter-level meaning. The baseline for 0-parameter tools is 4, and the description appropriately focuses on what is returned rather than input details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List all available vehicle types') on a clear resource, and adds example values that make the scope concrete. It also distinguishes itself from get_make_vehicle_types by emphasizing 'all' rather than a make-specific subset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool through 'all available vehicle types', but it does not explicitly contrast it with the sibling get_make_vehicle_types or state when a make-filtered alternative would be preferred. There is no direct when-to-use / when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode a World Manufacturer Identifier (WMI).
Returns manufacturer information for a 3- or 6-character WMI code (VIN positions 1-3, optionally + positions 12-14 for low-volume manufacturers).
| Name | Required | Description | Default |
|---|---|---|---|
| wmi | Yes | WMI code (3 chars for high-volume, 6 for low-volume manufacturers). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of explaining behavior. It communicates that this is a read-only lookup and defines the acceptable input scope, but it does not mention error handling, case sensitivity, or response format details. For a simple lookup tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. The core purpose is front-loaded, and the additional positional detail earns its place by improving input accuracy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter lookup with an output schema present, the description is essentially complete: it defines the input, its valid lengths, and the nature of the return value. Minor gaps like invalid-input behavior or character normalization are not critical for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the wmi parameter well, so the baseline is 3. The description adds useful context about VIN positions and the low-volume manufacturer scenario, which helps an agent construct a valid WMI argument beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Decode') and resource ('World Manufacturer Identifier'), and clarifies it handles 3- or 6-character WMI codes rather than full VINs. This clearly distinguishes it from siblings like decode_vin and decode_partial_vin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly signals the intended context: use this when you have a WMI code and need manufacturer information. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0decode_partial_vindecode_vinget_all_makesget_make_vehicle_typesget_model_yearsget_models_for_makeget_vehicle_typesget_wmi_infoScored across 8 tools
Most tools are clearly separated by resource and action: decode_* covers VIN/WMI decoding, get_* covers lookup tables. The only potential confusion is between decode_vin and decode_partial_vin, since decode_vin already accepts short VINs, though the wildcard/pattern use case is explicitly distinguished.
All tool names follow a consistent verb_noun pattern starting with decode_ or get_, and resource nouns are used predictably. The naming makes the set easy to scan and understand.
Eight tools is well-scoped for a VIN decoding and vehicle reference server. Each lookup tool has a clear purpose and the count is neither too sparse nor bloated.
The server covers the core VIN decode workflow (full and wildcard partial VINs, WMI info) and the supporting reference queries needed to explore makes, models, model years, and vehicle types. There are no obvious dead ends for the stated domain.
Machine-readable utilities and datasets for AI agents.
300+ deterministic data utilities for AI agents: validate, normalize, parse, match, redact.
15 deterministic validation tools for AI agents: tax IDs (15 countries), VAT, IBAN, LEI, HS codes.
Aircraft intelligence for AI agents: valuations with uncertainty bands, FAA registry lookups, cost of ownership, comparable aircraft, fleet search, airworthiness directives and STCs, market metrics and forecasts, verified value reports, pre-buy diligence checklists, logbook search and a watchlist. 38 tools; free tier with OAuth or a Windsock API key.
