Skip to main content
Glama
rachittshah

trucksim-mcp

by rachittshah

trucksim-mcp

一个 MCP 服务器,将 欧洲卡车模拟2 和 美国卡车模拟 的遥测数据——以及实时驾驶分析——流式传输到任何 AI 工具(Claude Desktop、Claude Code、Cursor、Cline 等)。包含一个无头 Claude 分析代理,充当驾驶室内的调度员/驾驶教练。

CI License: MIT Python 3.10+

向你的助手提问 "我超速了吗?"、"我能按时完成送货吗?"、"我的燃油续航怎么样?" 或 "给我目前的驾驶打个分"——它会根据实时游戏遥测数据来回答。这是一个只读的遥测与分析服务器:它绝不会控制卡车。

注意: "American Truck Simulator 2" 并不是一个独立的游戏——SCS 仍然只发布原版 ATS。ATS 和 ETS2 共享相同的引擎和遥测 SDK,因此 trucksim-mcp 无需任何配置即可同时支持两者。

工作原理

ETS2 / ATS ──(SCS Telemetry SDK)──▶ telemetry source ──▶ trucksim-mcp ──▶ any MCP client
                                     (mmap | http | mock)   (tools+analytics)   (Claude, Cursor…)

由于 SCS SDK 写入 Windows 共享内存,trucksim-mcp 通过可插拔的数据源读取遥测数据:

数据源

使用场景

需要游戏吗?

mock

演示、CI、开发——内置的脚本化行程

否

http

游戏运行在暴露 JSON 遥测源的 Windows PC 上(Funbit / trucksim-gps);可从任何地方读取

是(远程)

mmap

trucksim-mcp 与游戏运行在同一台 Windows PC 上

是(本地)

replay

回放你用 trucksim-mcp record 录制的真实驾驶

否

mock 数据源意味着整个流水线可以在任何操作系统上端到端运行,无需安装游戏; http 映射已针对真实捕获的数据进行了验证 (tests/fixtures/funbit_sample.json); trucksim-mcp selftest 可确认你的接线配置(并标记不合理的读数)。

Related MCP server: fastf1-mcp

快速开始

# no install, straight from GitHub (PyPI release pending)
TRUCKSIM_SOURCE=mock uvx --from git+https://github.com/rachittshah/trucksim-mcp trucksim-mcp

参见 docs/clients.md 了解 Claude Desktop / Cursor / Cline 配置,以及 docs/sources.md 了解如何接入真实的 ETS2/ATS 遥测数据。

连接你的本地 ETS2 / ATS

mock 数据源不需要游戏;要读取你的真实游戏,请选择一个数据源 (docs/sources.md 有完整指南):

跨平台(推荐)——游戏运行在 Windows 上,trucksim-mcp 可以 运行在你局域网内的任何地方:

  1. 将 SCS 遥测插件(RenCloud/scs-sdk-plugin)安装到游戏的 bin/win_x64/plugins/ 目录。

  2. 运行一个遥测 HTTP 服务器(Funbit/ets2-telemetry-server,端口 25555)。

  3. 在接触任何 MCP 客户端之前,先配置并验证接线:

    export TRUCKSIM_SOURCE=http
    export TRUCKSIM_HTTP_URL=http://<game-pc-ip>:25555/api/ets2/telemetry
    uvx --from git+https://github.com/rachittshah/trucksim-mcp trucksim-mcp selftest
    source: http
    connected: True
    game:   ets2
    speed:  84 km/h (limit 90)
    job:    Reefer  Frankfurt -> Munich
    ✅ Telemetry is live. Point your MCP client at this same config.

原生 Windows——trucksim-mcp 与游戏运行在同一台 PC 上:设置 TRUCKSIM_SOURCE=mmap(实验性)并运行 trucksim-mcp selftest。

然后在你的 MCP 客户端配置或 agent/mcp.json 中使用相同的环境变量。

工具

10 个只读工具——完整参考见 docs/tools.md:

  • 状态 — get_truck_state、get_navigation、get_fuel_status、get_raw_telemetry

  • 任务 — get_active_job

  • 分析 — check_speeding、get_eco_score、get_trip_summary、get_rest_advisor、list_recent_events

示例提示词

连接后(即使使用 TRUCKSIM_SOURCE=mock),向你的助手提问:

  • "我的卡车现在在做什么?" → get_truck_state

  • "我超速了吗?" → check_speeding

  • "我的燃油够开到目的地吗?" → get_fuel_status

  • "我能按时完成送货吗?" → get_active_job

  • "给我的驾驶打个分,告诉我需要改进什么。" → get_eco_score + get_trip_summary

  • "我该休息一下吗?" → get_rest_advisor

菜单栏应用(在游戏中与 Claude 对话)

两个 macOS 菜单栏应用提供实时遥测概览,以及一个浮动 Claude 聊天覆盖层,可显示在 ETS2/ATS 之上——无需离开游戏即可询问你的驾驶情况。完整指南:docs/menubar.md。

# Python (all-Python, pip install)
pip install "trucksim-mcp[menubar]" && TRUCKSIM_SOURCE=mock trucksim-mcp menubar

# Native SwiftUI (smoothest full-screen overlay) — see macos/TruckSimMenuBar/

两者都使用非激活的 NSPanel(fullScreenAuxiliary)浮动在游戏之上,因此 聊天窗口可以置顶显示而不会抢占焦点。

教练代理的实际效果

针对内置模拟行程运行无头代理——一个真实的 claude -p (Sonnet 5)通过此服务器读取遥测数据:

$ TRUCKSIM_AGENT_ONCE=1 ./agent/coach.sh

Heads up: your Hamburg steel-tubes job is projected LATE — ETA 7h7m vs a 4h59m
deadline, a 2h7m shortfall, so this delivery needs a route/time fix, not just
steady driving. Speed and fuel are fine: you're well under the 90 km/h limit,
damage is only 3%, and fuel (688L, ~2149 km range) easily covers the 285 km
trip. Recommendation: check for a faster route or accept the late penalty now.

无头分析代理

agent/ 包含一个后台 Claude Code 无头(claude -p,Sonnet 5) 运行器, 它连接到此 MCP 服务器,并根据实时遥测数据生成周期性的驾驶室内教练更新—— 一个没有语音的调度员。参见 agent/README.md。

文档

指南

内容

docs/tools.md

全部 10 个 MCP 工具的生成参考。

docs/clients.md

将服务器添加到 Claude Desktop / Claude Code / Cursor / Cline / Windsurf。

docs/sources.md

接入真实遥测数据(mock / http / mmap)+ 调优。

docs/menubar.md

两个 macOS 菜单栏应用和游戏内聊天覆盖层。

agent/README.md

无头 claude -p 教练代理。

macos/TruckSimMenuBar/README.md

构建原生 SwiftUI 应用。

evals/README.md

自动化、评分的评估框架。

CONTRIBUTING.md · CHANGELOG.md · RELEASING.md

贡献指南、发布说明和 PyPI 发布流程。

许可证

MIT © Rachitt Shah。与 SCS Software 无关联,也未获得其认可。 Euro Truck Simulator 2 和 American Truck Simulator 是 SCS Software 的商标。

Available Tools

10 tools
check_speedingA
Read-onlyIdempotent

Are you speeding right now, and by how much over the posted limit?

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

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

The annotations already establish this as a safe, read-only, idempotent query. The description adds useful behavioral context by specifying that it evaluates the current situation and compares against the posted limit, rather than raw speed alone. Nothing in the description contradicts the annotations.

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?

The description is a single, efficient sentence that communicates the core purpose and key qualifiers (right now, posted limit) without redundancy. It is front-loaded and free of unnecessary detail.

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?

For a zero-parameter, read-only tool with an output schema and strong safety annotations, the description covers everything needed to invoke it appropriately. The combination of annotations, output schema, and succinct description leaves no significant contextual gap.

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?

The tool has zero parameters and the schema covers 100% of the parameter surface, so there is little parameter information to add. The description's mention of 'posted limit' gives helpful semantic framing even though no parameters exist.

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?

The description clearly identifies the tool's function: determining whether the subject is currently speeding and by how much over the posted limit. While phrased as a question rather than an imperative-style description, it is specific and distinguishable from sibling tools like get_truck_state or get_raw_telemetry.

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

Usage Guidelines3/5

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

The description implies the tool should be used when the current speeding status relative to the posted limit is needed. However, it does not explicitly explain when to prefer this tool over alternatives or mention any exclusions, leaving comparison with sibling tools to inference.

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

get_active_jobA
Read-onlyIdempotent

The current delivery job: cargo, route, pay, deadline, and on-time status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no additional behavioral context (e.g., latency, freshness, or what happens if no active job exists). Since annotations carry the burden, a 3 is appropriate; the description does not contradict them.

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?

The description is a single, information-dense sentence. It front-loads the core content (current delivery job) and lists the returned fields without any filler. Every word earns its place, making it exceptionally concise and well-structured.

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?

For a zero-parameter, read-only tool with an output schema available and annotations covering behavioral safety, the description is complete. It specifies the key content returned, and the output schema handles the exact structure. Nothing an agent needs to decide whether to call this tool is missing.

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?

The tool has zero parameters, so schema description coverage is trivially 100%. The description does not need to explain any parameters. Per the rubric, 0 params yields a baseline of 4, and the description adds no unnecessary detail.

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?

The description clearly states the resource (current delivery job) and the specific attributes it returns (cargo, route, pay, deadline, on-time status). It unambiguously identifies the tool's function and differentiates it from sibling getters like get_truck_state or get_fuel_status by focusing on the job itself.

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

Usage Guidelines3/5

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

The description implies the tool is for retrieving current job details, but it does not explicitly state when to use it versus alternatives. There is no context about prerequisites or exclusions, but given the simplicity of a zero-parameter getter, the usage is reasonably inferable from the name and description. It meets the 'implied usage' bar.

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

get_eco_scoreA
Read-onlyIdempotent

A 0-100 driving score for this session, with the factors dragging it down.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

The annotations already declare readOnly, idempotent, and openWorld hints, so the safety profile is covered. The description adds useful semantic context (score range and contributing factors) beyond the annotations, but it does not disclose any additional behavioral traits such as data staleness or calculation basis. Given the annotations carry the main burden, a 3 is appropriate.

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?

The description is a single, dense sentence that front-loads the key output (0-100 score) and immediately notes the inclusion of affecting factors. There is no filler or repetition; every word contributes to understanding.

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 simple read-only tool with no parameters and an output schema present, the description sufficiently explains what the score represents and its range. It could benefit from a note on when to use it over sibling tools, but that falls under usage guidelines. Overall, the tool is adequately specified for invocation.

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?

There are zero parameters, so the schema is fully self-explanatory. The description adds no parameter information, but none is needed. The baseline of 4 applies due to the absence of parameters.

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?

The description clearly states the tool returns a 0-100 driving score for the current session, and mentions that it includes the factors that lower it. This is a specific resource ('driving score') with a precise range and context, distinguishing it from sibling tools like get_trip_summary or get_raw_telemetry.

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

Usage Guidelines2/5

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

No guidance is given on when to use this tool versus alternatives such as get_trip_summary or check_speeding. The description only states what it does, not when it is appropriate or when another tool should be preferred. This leaves the agent to infer usage context from the name and siblings.

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

get_fuel_statusA
Read-onlyIdempotent

Fuel level, consumption, estimated range, and whether it's enough to reach the routed destination.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the specific data fields returned but does not reveal any additional behavioral traits (e.g., data freshness, side effects, or error conditions). With annotations covering the core behavior, a score of 3 is appropriate.

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?

A single, compact sentence lists all four data points without any filler. It is front-loaded with the most important information (fuel level) and efficiently covers the rest.

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?

Given there are no parameters and an output schema exists, the description fully communicates the tool's purpose and return value. An agent can confidently call this tool without additional context.

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?

The tool has zero parameters, so no parameter-specific documentation is needed. The description's mention of the routed destination implies that navigation context is automatically used, but since no parameters exist, the baseline of 4 applies.

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?

The description states precisely what the tool returns: fuel level, consumption, estimated range, and a binary judgment about reaching the routed destination. This is specific, names the resource (fuel status), and clearly distinguishes it from siblings like get_navigation or get_truck_state.

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

Usage Guidelines3/5

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

The description implies the tool is for fuel-related queries, but it does not explicitly state when to use it over alternatives or any exclusions. Given its narrow scope, the intended use is fairly obvious, but the lack of explicit routing guidance leaves room for ambiguity.

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

get_navigationA
Read-onlyIdempotent

Routing status: distance and ETA to the destination, posted limit, and whether you're currently speeding.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value by specifying the exact content returned (distance, ETA, posted limit, speeding). It does not cover edge cases (e.g., no active route), but given the annotations and the simplicity of the tool, the added context 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.

Conciseness5/5

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

The description is a single, front-loaded sentence that begins with the core resource ('Routing status') and lists the returned fields immediately. Every word is informative with no redundancy.

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?

Given the tool has no parameters, an output schema exists, and annotations cover safety, the description fully explains the tool's purpose and scope. Nothing needed for correct invocation or understanding is missing.

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?

The tool has zero parameters, so the schema is empty and the description carries no parameter-specific burden. The description conveys the semantic output meaning, which fully compensates for the lack of parameters. Baseline of 4 is appropriate.

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?

The description clearly states a specific resource ('Routing status') and the precise data returned (distance, ETA, posted limit, speeding status). It is distinct from siblings like get_truck_state or get_fuel_status, which deal with other domains.

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

Usage Guidelines3/5

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

The description implies usage for retrieving routing information but does not explicitly contrast with alternatives such as check_speeding (which focuses solely on speeding) or get_trip_summary. No when-not-to-use or alternative routing is provided, so the agent must infer from context.

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

get_raw_telemetryA
Read-onlyIdempotent

The full normalized telemetry snapshot as JSON (for power users / debugging).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining the output is a 'full normalized telemetry snapshot', indicating the data is normalized and complete, which is behavioral context not present in the annotations. This enhances understanding without contradicting any annotation.

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?

The description is a single, front-loaded sentence that immediately states the core purpose ('full normalized telemetry snapshot as JSON') and then adds a clarifying audience note. Every word earns its place, with no filler or redundancy. It is concise and well-structured.

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 zero-parameter tool with an output schema already defined, the description is sufficient. It states what the tool returns and who it is intended for. It does not explicitly mention when to prefer siblings, but the 'full' vs specific distinction is implied, and the presence of an output schema means return format is already documented. Overall, it covers what an agent needs to invoke it correctly.

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?

The tool has zero parameters and schema description coverage is trivially 100% because there are no properties to document. The baseline for 0 parameters is 4, and the description does not need to explain parameters. It adds no parameter-specific information, but none is required.

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?

The description states the tool returns 'the full normalized telemetry snapshot as JSON', which clearly identifies the resource and the format. The qualifiers 'full' and 'normalized' help distinguish it from siblings like get_truck_state or get_fuel_status, though it does not explicitly name a sibling or contrast itself. This is clear and specific enough to avoid confusion.

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?

The description says it is 'for power users / debugging', which implies the intended use case: when a user needs the complete raw snapshot for debugging rather than a focused subset. It does not explicitly state when not to use it or name alternative tools, but the user audience hint provides clear context about when this tool is appropriate.

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

get_rest_advisorA
Read-onlyIdempotent

Fatigue guidance based on continuous driving time (EU hours-of-service style).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

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

Annotations already convey read-only, idempotent, and non-destructive behavior, so the description need not repeat these. It does add the context of EU hours-of-service style, which hints at the regulatory framework behind the guidance. However, it does not disclose any edge cases, data availability limits, or the nature of the output beyond 'guidance.' Given the low complexity and strong annotations, this is adequate but not exceptional.

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?

The description is a single, front-loaded sentence with no filler. It states the core purpose ('Fatigue guidance') first, then clarifies the basis ('continuous driving time') and adds a contextual qualifier ('EU hours-of-service style'). Every word earns its place, and it is appropriately sized for a zero-parameter tool.

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?

Given the tool has no parameters and an output schema exists (which we don't see but is present), the description sufficiently conveys what the tool does. It could be enhanced by explicitly stating when to call it (e.g., 'Use when the driver has been driving for a sustained period'), but it is currently adequate for an agent to understand its role among the sibling tools. The lack of any handling instructions for missing or invalid data is a minor gap.

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?

With zero parameters, the baseline is 4 per the rubric. The description's mention of 'continuous driving time' clarifies the conceptual input even though no explicit parameter exists, helping the agent understand what data drives the guidance. This adds value beyond the empty schema.

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?

The description clearly states a specific verb ('get') and resource ('rest advisor') with a precise function: providing fatigue guidance based on continuous driving time. It is distinct from sibling tools such as get_truck_state, get_navigation, and get_eco_score, which cover unrelated domains. The EU hours-of-service mention adds domain context without ambiguity.

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

Usage Guidelines3/5

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

The description implies the tool is relevant when continuous driving time is a factor, but it does not explicitly state when to use it versus alternatives, nor does it mention exclusion criteria. Since no sibling tool provides fatigue guidance, the lack of explicit alternatives is acceptable, but it still lacks a clear 'use when' statement. The phrase 'based on continuous driving time' gives an implicit trigger, but more explicit guidance would improve clarity.

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

get_trip_summaryA
Read-onlyIdempotent

Rolling trip totals since the server started: distance, time, speeds, fuel, events.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the temporal context ('since the server started'), which is valuable behavioral information beyond the annotations. It does not elaborate on return structure, but that is covered by the output schema.

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?

The description is a single, front-loaded sentence with no wasted words. Every element ('rolling totals', 'since server started', the list of data types) earns its place, making it instantly scannable.

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?

Given that the tool takes no parameters and an output schema exists, the description is sufficiently complete. It defines the time window and the content of the summary, leaving the return format to the schema. An agent can call it without ambiguity.

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?

There are zero parameters, so the baseline for this dimension is 4. The description correctly avoids mentioning any parameters, and the schema is empty, so there is nothing to add.

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?

The description states a specific verb ('get'), a resource (trip summary), and the scope ('rolling totals since the server started'), while enumerating the data categories (distance, time, speeds, fuel, events). This clearly distinguishes it from siblings like get_fuel_status or get_truck_state, which focus on narrower aspects.

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

Usage Guidelines3/5

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

The description conveys the use case (retrieving overall trip aggregates) but provides no explicit guidance on when to choose this over alternatives. It does not mention exclusions or contrast with sibling tools, leaving the selection to inference.

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

get_truck_stateA
Read-onlyIdempotent

Current truck state: speed vs limit, engine, gear, cruise, fuel, damage, lights.

The one-call "what's happening right now" snapshot. Works with any configured source (mock/http/mmap).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds useful context by noting it works with any configured source (mock/http/mmap), indicating backend-agnostic behavior and the snapshot nature, which goes beyond the annotations without contradicting them.

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?

The description is two concise sentences. The first lists the included state aspects, and the second frames the tool's primary use case and backend flexibility. Every sentence carries meaning and the most important information is front-loaded.

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?

Given the tool has no parameters, is read-only with comprehensive annotations, and has an output schema, the description fully covers the essential context. It explains what the tool does, what data is returned, and that it works across sources, so no critical information is missing.

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?

There are zero parameters, so the schema description coverage is 100% by vacuity. Per the baseline rule for 0-parameter tools, a score of 4 is appropriate; the description does not need to compensate for missing parameter documentation.

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?

The description clearly states the tool fetches the 'current truck state' and enumerates the specific data aspects it covers (speed vs limit, engine, gear, cruise, fuel, damage, lights). It also brands itself as a 'one-call snapshot', which effectively differentiates it from more specialized sibling tools like get_fuel_status or get_navigation.

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 frames the tool as the go-to for a comprehensive 'what's happening right now' overview, which implicitly advises using it when a broad state is needed rather than a single metric. However, it does not explicitly name alternative tools or exclusion criteria, so the guidance is clear but not fully explicit.

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

list_recent_eventsA
Read-onlyIdempotent

Recent driving events (speeding, hard braking, collisions, refuels), newest first.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax events to show.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety and idempotency profile is covered. The description adds the behavioral traits of ordering (newest first) and scope (driving events including specific categories). It doesn't mention pagination or default limit behavior, but that is partially covered by the schema default. Given the annotations provide a strong baseline, the description adds useful context beyond them.

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?

A single sentence that is concise and front-loads the core purpose (recent driving events) before enumerating event types and ordering. No filler words.

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?

The tool has an output schema (though not shown here, it's indicated as present), and the description doesn't need to explain return format. Combined with annotations and schema, the description is sufficient for an agent to know what it returns and when to call it. Minor gap: no mention of how events are categorized or whether filters exist beyond limit, but that may be beyond scope for a simple list tool.

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

Parameters3/5

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

Schema coverage is 100% (the only parameter `limit` has a description). The description does not add additional parameter semantics beyond what's in the schema, but the parameter itself is simple and well-covered. Baseline 3 is appropriate when the schema already documents the parameter effectively.

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?

The description clearly states the resource (recent driving events) and the specific event types (speeding, hard braking, collisions, refuels), and notes the ordering (newest first). This distinguishes it from sibling tools like get_raw_telemetry or get_trip_summary, which are either more raw or aggregate differently. The verb 'list' is explicit.

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

Usage Guidelines3/5

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

The description implies a general-purpose listing use case but does not explicitly state when to use this vs. alternatives. Sibling tools like check_speeding or get_trip_summary might cover similar ground, but no exclusion or preference guidance is given. The ordering and event type filtering are clear, but no scenarios are provided.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updatesv0.2.0
    • First observedcheck_speeding
    • First observedget_active_job
    • First observedget_eco_score
    • First observedget_fuel_status
    • First observedget_navigation
    • First observedget_raw_telemetry
    • First observedget_rest_advisor
    • First observedget_trip_summary
    • First observedget_truck_state
    • First observedlist_recent_events

TDQS

A4/5.0

Scored across 10 tools

Disambiguation4/5

Each tool targets a distinct aspect of the truck state (speed, fuel, navigation, job, etc.), but there is some overlap: get_truck_state includes speed/fuel while check_speeding and get_fuel_status focus on those specifically. Descriptions clarify the focus, so agents can generally select correctly.

Naming Consistency3/5

Most tools follow a get_ verb pattern, but check_speeding and list_recent_events break the convention with different verbs. This is more than a minor deviation, though still readable and predictable overall.

Tool Count5/5

With 10 tools, the server is well-scoped for a truck telemetry/monitoring purpose. Each tool has a clear role, and none feel redundant or missing at this granularity.

Completeness4/5

The tool set covers a broad range of truck and driver status (state, navigation, fuel, job, speeding, eco, trip, rest, events, raw data). Missing operations like historical queries or filtered events are minor gaps that most workflows can work around.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    MCP server combining TeslaMate historical analytics with Fleet API live data and commands. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
    29
    2
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    A local MCP server that gives Claude (or any MCP-compatible AI client) access to Formula 1 race data. Load any session from 2018 onwards, ask questions in natural language, and get answers backed by real telemetry, timing, and strategy data.
    4
    17
    1
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    This MCP server provides real-time integration between Elite Dangerous and Claude Desktop, enabling AI-powered analysis of your gameplay data and dynamic generation of EDCoPilot custom content.
    3
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Local MCP server that connects Claude Desktop with Garmin and Apple Health data to read training and recovery, estimate heart rate and pace zones, analyze performance, and create structured workouts.
    22
    MIT