italian-bus-search

Search Italian bus journeys

search_journeys

Read-onlyIdempotent

Search one-way bus and coach journeys across multiple Italian operators, returning normalized results with official booking links; use for buses only, not trains or rail.

Instructions

BUS ONLY. Search one-way bus/coach journeys. Never use for trains or rail; use search_train_journeys instead. Results include official links for continuing manually on provider sites. For stable pagination start with snapshot:true; continue using only searchId, offset and limit.

Input Schema

Name	Required	Description
`date`	No	Real future date in YYYY-MM-DD format
`limit`	No
`adults`	No
`offset`	No	Result offset; add limit while truncated is true
`origin`	No	Exact shared location name for aggregate searches, or a provider-specific ID when provider is set
`children`	No
`provider`	No	Provider ID; omit to search every provider
`searchId`	No
`snapshot`	No
`destination`	No	Exact shared location name for aggregate searches, or a provider-specific ID when provider is set

Output Schema

Name	Required	Description	Default
`total`	Yes
`errors`	Yes
`journeys`	Yes
`searchId`	No
`createdAt`	No
`expiresAt`	No
`truncated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv0.3.6Oct 29, 2026

removedInput schema / properties / adults / default
```
Removed value: -1
```
removedInput schema / properties / children / default
```
Removed value: -0
```

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Result offset; add limit while truncated is true",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / searchId
```
Added value: +{
+  "type": "string"
+}
```

addedInput schema / properties / snapshot

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

removedInput schema / required

Removed value: -[
-  "origin",
-  "destination",
-  "date"
-]

addedOutput schema / properties / createdAt
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / errors / items / properties / code / enum

Previous value: -[
-  "INVALID_INPUT",
-  "UNKNOWN_LOCATION",
-  "NO_JOURNEYS",
-  "PROVIDER_UNAVAILABLE",
-  "INCOMPATIBLE_RESPONSE",
-  "RATE_LIMITED",
-  "AMBIGUOUS_LOCATION",
-  "COVERAGE_UNAVAILABLE",
-  "QUOTE_UNAVAILABLE",
-  "LIVE_STATUS_UNAVAILABLE",
-  "TRAIN_NOT_FOUND"
-]New value: +[
+  "SEARCH_EXPIRED",
+  "SEARCH_TOO_LARGE",
+  "INVALID_INPUT",
+  "UNKNOWN_LOCATION",
+  "NO_JOURNEYS",
+  "PROVIDER_UNAVAILABLE",
+  "INCOMPATIBLE_RESPONSE",
+  "RATE_LIMITED",
+  "AMBIGUOUS_LOCATION",
+  "COVERAGE_UNAVAILABLE",
+  "QUOTE_UNAVAILABLE",
+  "LIVE_STATUS_UNAVAILABLE",
+  "TRAIN_NOT_FOUND"
+]

addedOutput schema / properties / expiresAt
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / journeys / items / properties / destination / properties / address
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / journeys / items / properties / destination / properties / city
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / journeys / items / properties / origin / properties / address
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / journeys / items / properties / origin / properties / city
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / searchId
```
Added value: +{
+  "type": "string"
+}
```

Changed4 schema fields changedv0.3.2Oct 26, 2026

changedInput schema / properties / destination / description

Previous value: -"Exact location name or ID returned by search_locations"New value: +"Exact shared location name for aggregate searches, or a provider-specific ID when provider is set"

changedInput schema / properties / limit / default
```
Previous value: -10New value: +50
```

changedInput schema / properties / origin / description

Previous value: -"Exact location name or ID returned by search_locations"New value: +"Exact shared location name for aggregate searches, or a provider-specific ID when provider is set"

changedOutput schema / properties / errors / items / properties / code / enum

Previous value: -[
-  "INVALID_INPUT",
-  "UNKNOWN_LOCATION",
-  "NO_JOURNEYS",
-  "PROVIDER_UNAVAILABLE",
-  "INCOMPATIBLE_RESPONSE",
-  "RATE_LIMITED"
-]New value: +[
+  "INVALID_INPUT",
+  "UNKNOWN_LOCATION",
+  "NO_JOURNEYS",
+  "PROVIDER_UNAVAILABLE",
+  "INCOMPATIBLE_RESPONSE",
+  "RATE_LIMITED",
+  "AMBIGUOUS_LOCATION",
+  "COVERAGE_UNAVAILABLE",
+  "QUOTE_UNAVAILABLE",
+  "LIVE_STATUS_UNAVAILABLE",
+  "TRAIN_NOT_FOUND"
+]

First observedv0.1.2Oct 24, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is met without prose. The description adds genuine non-schema behavior: results carry official provider links for manual continuation, and snapshot:true is required for stable pagination. It does not mention rate limits or result ordering, which keeps it below a 5.

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

Conciseness5/5

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

Four short sentences, zero filler, with the mode restriction front-loaded and the alternative and pagination protocol following in priority order. Every clause carries operational information.

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?

With 10 parameters, partial schema coverage and an output schema that already documents return values, the description supplies exactly the missing operational pieces: the snapshot/searchId pagination protocol and the manual-continuation nature of results. Passenger and date parameter handling is left implicit, a minor gap for a zero-required-parameter tool.

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 only 50%, so the description must compensate—and it does for the trickiest fields: snapshot:true semantics and the constraint that continuation pages use only searchId, offset and limit (not the original search criteria). adults, children and the limit maximum are left to the schema, so not full marks.

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

Purpose5/5

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

"BUS ONLY. Search one-way bus/coach journeys" gives a specific verb plus resource and an explicit transport-mode scope. It also names the sibling it must not be confused with (search_train_journeys), so an agent can discriminate it without opening any schema.

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

Usage Guidelines5/5

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

Explicit negative guidance ("Never use for trains or rail; use search_train_journeys instead") plus a positive workflow rule for pagination (start with snapshot:true, then continue using only searchId, offset and limit). Both when-to-use and when-not-to-use are stated.

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

Deploy Server