Decodifica VIN y consulta datos de vehículos desde una base de datos curada de NHTSA vPIC, impulsada por el Model Context Protocol.
Un servidor MCP independiente y capaz de funcionar sin conexión para que los LLM puedan decodificar númer os de identificación del vehículo (VIN) y consultar marcas, mode los y especificaciones de vehículos utilizando datos de vPIC de NHTSA.
pip install vin-decode-mcp
vin-decode-mcp # Start the MCP serverSin conexión: Funciona sin acceso a internet. La base de datos SQLite curada (~4.5 MB) es autónoma.
Sin límites de peticiones: A diferencia de llamar directamente a la API de vPIC, las consultas locales son ilimitadas.
Rápido: La coincidencia de patrones con la base de datos SQLite toma microsegundos.
Nativo para LLM: Herramientas con docstrings enriquecidos, recursos de esque ma y salida JSON estructurada.
Datos abiertos: NHTSA vPIC es datos abiertos del gobierno de EE. UU.: gratuito, sin necesid ad de clave API.
Related MCP server: VIN MCP
Vehículos del mercado de EE. UU., año de mode lo 1981 y posteriores
534 marcas, 9,175 mode los, 88,140 patrones de VIN
Automóviles de pasajeros, camiones, MPV, motocicletas, vehículos todo terrenos
Excluye: autobuses, remolques, vehículos de baja velocid ad, vehículos incompletos
Solo especificaciones: esta base de datos no incluye historial de títuo, accidentes, odómetro ni robos (eso requiere fuentes de datos NMVTIS/comerciales).
pip install vin-decode-mcpO desde el códi go fuente:
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 8765Añade lo siguiente a ~/.config/claude-desktop/config.json (o ~/Library/Application Support/claude-desktop/config.json en macOs):
{
"mcpServers": {
"vin-decode": {
"command": "vin-decode-mcp"
}
}
}Reinicia Claude Desktop. El mode lo ahora puede usar las her ramientas de decodificación de VIN en las conversaciones.
Her ramienta | Descripción |
| Decodificar un VIN → marca, modelo, año, tipo de vehículo |
| Coincidir con un VIN parcial mediante comodines |
| Listar todas las marcas de vehículos |
| Listar los mode los de una marca |
| Obtener el rango de años de producción |
| Decodificar un WMI → información del fabricante |
| Listar los tipos de vehículo disponibles |
| Listar los tipos de vehículo de una marca |
>>> 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"}]La base de datos compilada está alojada en Hugging Face:
Conjunto de datos: https://hugingface.co/datasets/vin-decode-mcp/vpic-database Descarga directa: https://hugingface.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.dbLa base de datos se reconstruye a partir de las bases de datos PostgresQL independientes de NHTSA aproximadamente cada 6-12 meses:
# 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.dbConsulta docs/hf-setup.md para las instrucciones de configuración de Hugging Face.
Los datos de vehículos provienen de vPIC de NHTSA — el Vehicle Product Information Catalog y el Vehicle Listing de la National Highway Traffic Safety Administration. NHTSA es una agencia del gobierno de los Estados Unidos.
Licencia de datos: trabjo del gobierno de EE. UU. (dominio púbico)
API: no se requiere clave ni registro
Frecuencia de actualización: ~6-12 meses
Informar errores: contacta con el servicio de asistencia al fabricante de NHTSA en manufacturerinfo@dot.gov o al 1-888-399-3277
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) | |
Transporte | SQLite local | HTTP REST | HTTP REST |
Sin conexión | ✅ | ❌ | ❌ |
Límite de peticiones | No | Sí | Sí |
Tamaño de los datos | ~4.5 MB | N/A | N/A |
Campos de VIN | Marca + Modelo + Año | ~130 campos | ~130 campos |
Marcas/Modelos | ✅ 534/9,175 | ✅ Catálogo completo | ✅ Catálogo completo |
Instalación |
| Ninguno |
|
Licencia MIT — El código es MIT. Los datos son de dominio público del gobierno de EE. UU.
Consulta LICENSE para más detalles.
¡Las contribuciones son bienvenidas! Por favor:
Haz un fork y crea una rama de funcionalidad
Añade pruebas para la nueva funcionalidad
Asegúrate de que el CI pase
Envía una pull request
Para cambios importantes, abre un issue primero para discutir el enfoque.
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.
