ViaggiaTreno MCP Server

Elenco Tratte Ferroviarie

elenco_tratte_ferroviarie

Retrieve railway network segments with coordinates and real-time occupancy by trains, filtered by category or Italian region to analyze live traffic and segment usage.

Instructions

Restituisce i segmenti della rete ferroviaria (coppie di nodi ferroviari con coordinate geografiche) e l'indicazione se ciascun segmento è attualmente occupato da almeno un treno in viaggio. Le categorie filtrabili (separate da virgola) includono: 'ES*,IC,EXP,EC,EN,REG'. id_regione filtra i segmenti per area geografica (0=tutta Italia, 1-22=singola regione, stesso codice di elenco_stazioni/regione): attenzione, filtra i segmenti non i treni, quindi un segmento di confine regionale può comunque restituire treni di lunga percorrenza che solo transitano in quell'area. Gli ID tratta_ab/tratta_ba restituiti sono numerati per regione: vanno riusati con lo stesso id_regione in treni_su_tratta, altrimenti si ottengono i treni di un segmento fisicamente diverso.

Input Schema

Name	Required	Description	Default
`categorie`	No		ES*,IC,EXP,EC,EN,REG
`id_regione`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.2.0Oct 24, 2026

addedInput schema / properties / id_regione

Added value: +{
+  "default": 0,
+  "type": "integer"
+}

changedOutput schema / properties / result / items / description

Previous value: -"Segmento della rete ferroviaria tra due nodi (elencoTratte)."New value: +"Segmento della rete ferroviaria tra due nodi (elencoTratte).\n\nNota: ``trattaAB``/``trattaBA`` sono numerati **per regione**: lo stesso ID\npuò indicare segmenti fisicamente diversi secondo l'``id_regione`` usato\nnella chiamata a ``elenco_tratte``. Vanno passati a ``dettagli_tratta``\ninsieme allo stesso ``id_regione`` con cui sono stati ottenuti, altrimenti\nsi rischia di leggere i treni di un segmento completamente diverso senza\nnessun errore (verificato dal vivo, vedi VIAGGIATRENO.md)."

changedOutput schema / properties / result / items / properties / trattaAB / description

Previous value: -"Identificativo numerico del segmento in direzione A -> B"New value: +"Identificativo numerico del segmento in direzione A -> B (scoped per regione)"

changedOutput schema / properties / result / items / properties / trattaBA / description

Previous value: -"Identificativo numerico del segmento in direzione B -> A"New value: +"Identificativo numerico del segmento in direzione B -> A (scoped per regione)"

First observedv0.1.0Oct 4, 2026

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description carries the burden and does well: it discloses that region filtering applies to segments (not trains), that border segments can return long-distance trains merely transiting, and that tratta IDs are region-scoped and must be reused with the same id_regione. No mention of rate limits, pagination, or auth, but the meaningful behavioral traps are surfaced.

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 what the tool returns, then parameter semantics, then the critical caveats — every sentence adds information. It is dense and sentence length in the id_regione explanation is high, but nothing is truly redundant.

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

Completeness5/5

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

An output schema exists, so return shape needn't be restated; the description still covers the returned content (segments, coordinates, occupancy, tratta_ab/ba IDs) and the cross-tool ID-reuse rule. For a two-param read tool, an agent has everything needed to call it correctly.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, yet the description fully documents both parameters: categorie with concrete example values, and id_regione with the full code space (0=tutta Italia, 1-22=singola regione) plus a pointer to elenco_stazioni/regione for codes. It adds semantic depth the bare schema defaults could never convey.

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?

States a specific verb and resource ('Restituisce i segmenti della rete ferroviaria') plus what each segment carries (coppie di nodi con coordinate, indicazione di occupazione). It also implicitly distinguishes itself from treni_su_tratta by describing segments rather than trains, so an agent can tell the two apart without reading schemas.

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?

It explains the segment-vs-train filtering distinction and explicitly names treni_su_tratta as the downstream consumer of the returned IDs, which gives clear usage context. What's missing is an explicit 'use this tool when you need X, use treni_su_tratta when you need Y' routing statement, and any prerequisites are only implied.

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