API Ninjas

getCars

Read-only

The main endpoint. Search the whole catalogue by any combination of filters, or fetch cars you already know with id/ids. Every car is returned with its complete specification sheet attached, so no second call is needed. Each row also carries its own make, model, generation, body and engine context. At least one filter, or an id, is required. The total number of matches is returned in the X-Total-Count response header. Requires a paid plan (Premium).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "getCars"
  }
}

Input Schema

Name	Required	Description
`id`	No	A car handle from a previous search, e.g. car_e71ff3416a. Safe to store: it is derived from the car's identity and survives data refreshes.
`ids`	No	Comma-separated car handles, at most 50. Request order is preserved and a handle matching nothing is returned as null.
`body`	No	Body style. One of Sedan, Coupe, Convertible, Wagon, Hatchback, Liftback, SUV, MPV, Van, Pickup.
`fuel`	No	Fuel type.
`make`	No	Manufacturer, as a word. Case and punctuation are ignored, so bmw, BMW and Bmw all resolve.
`sort`	No	Sort order.
`year`	No	Cars in production in this year. A filter, not a starting point.
`badge`	No	Model designation, e.g. 320d. Spacing and case are ignored.
`doors`	No	Number of doors.
`drive`	No	Driven wheels.
`limit`	No	How many results to return, between 1 and 100. Default 10 -- each car carries a full specification sheet of roughly 2 KB. A value outside the range is rejected rather than silently clamped.
`model`	No	Model, as a word. '3 Series', '3-series' and '3series' all resolve.
`offset`	No	Number of results to skip, for pagination. Default 0.
`max_year`	No	Cars in production in or before this year.
`min_year`	No	Cars still in production in or after this year.
`cylinders`	No	Number of cylinders.
`generation`	No	Generation, as a word, e.g. e90 or 'E90/E91/E92/E93'. Optional -- nothing requires going through a generation.
`engine_code`	No	Manufacturer engine code.
`chassis_code`	No	Filter to one chassis code, e.g. E91. Matches anything whose chassis_codes contains it.
`max_power_hp`	No	Maximum engine power in horsepower.
`min_power_hp`	No	Minimum engine power in horsepower.
`transmission`	No	Transmission type.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 9, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already establishes this as a safe read. The description adds real operational context beyond that: a paid-plan (Premium) prerequisite and the X-Total-Count response header carrying the match count. It does not discuss rate limits or pagination edge cases, but with annotations covering safety, this is solid added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with 'The main endpoint' before the search/lookup duality, then the return shape, the constraint, the header, and the plan requirement. Every sentence carries information, though the return-shape sentence overlaps slightly with what the limit parameter already documents.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 22-parameter, no-output-schema tool, the description supplies the essentials: what is returned, how to control volume (via the schema's limit/offset), the required-input rule, and the total-count header. Pagination specifics live in the schema, so nothing critical is missing, though output format nuance is only lightly sketched.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 meaning the schema does not: the non-obvious constraint that at least one filter or id is required despite the empty required array, and the promise that each row carries a full specification sheet with make/model/generation/body/engine context. That compensating detail lifts it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource – searching the car catalogue or fetching known cars by id/ids – and positions itself as 'the main endpoint', which implies scope beyond the narrower siblings (getCarMakes, getCarModels, getCarFacets). It does not name those siblings explicitly, so the differentiation is inferential rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly separates the two modes of use (search by filters vs. lookup by id/ids) and states the precondition that at least one filter or an id is required. It mentions the Premium requirement, giving a gating condition. It stops short of routing the agent to sibling tools like getCarFacets or getCarMakes, which would complete the guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All API Ninjas tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?