Skip to main content
Glama
deenesjakoruzh
RyK57

transit

by RyK57
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

transit-mcp-server

用于 511.org SF Bay Open Data 公交 API 的 MCP 服务器。为 LLM 提供实时的湾区公交数据——包括运营机构、线路、站点、实时发车信息、车辆位置和服务警报——覆盖 BART、Muni、AC Transit、Caltrain、VTA 以及所有其他向 511 报告的运营机构。

6 个工具，全部只读。

要求

Related MCP server: mcp-bart

安装

npm install
npm run build

配置

{
  "mcpServers": {
    "transit": {
      "command": "node",
      "args": ["/absolute/path/to/transit-mcp-server/dist/index.js"],
      "env": { "TRANSIT_511_API_KEY": "your-token-here" }
    }
  }
}

变量

是否必需

默认值

用途

TRANSIT_511_API_KEY

是

—

来自 https://511.org/open-data/token 的令牌

TRANSIT_511_BASE_URL

否

https://api.511.org

覆盖 API 主机

TRANSIT_511_REQUEST_TIMEOUT_MS

否

30000

每次请求的超时时间

TRANSPORT

否

stdio

stdio 或 http

PORT / HOST

否

3000 / 127.0.0.1

HTTP 传输绑定地址

MCP_PATH_SECRET

托管时

—

在 /mcp/<secret> 提供端点。当 HOST 不是回环地址时必需

ALLOWED_ORIGINS

否

localhost + claude.ai

逗号分隔的来源允许列表

配额是主要限制

511 允许每个密钥每小时 60 次请求，所有端点共享。这个限制足以影响这些工具的使用方式：

  • 一次性解析运营机构代码和站点代码，然后重复使用。它们不会改变。

  • 优先使用不带 operator_id 的 transit_list_service_alerts——一次调用即可覆盖所有机构。

  • 切勿循环轮询 transit_next_departures。通勤途中十次检查就占用了每小时预算的六分之一。

transit_list_operators 会报告剩余预算，该值从 511 在每个响应中返回的 RateLimit-Remaining 头读取。超出配额会返回 429；如需增加配额，请联系 transitdata@511.org。

部署（用于 Claude 移动端 / claude.ai 连接器）

与任何托管的 MCP 服务器相同：使用 openssl rand -hex 32 生成路径密钥，在平台仪表板中设置 TRANSIT_511_API_KEY 和 MCP_PATH_SECRET，附带的 Dockerfile 和 railway.json 可直接在 Railway、Render 或 Fly 上使用。没有密钥时，服务器拒绝在公共接口上启动。/healthz 是一个无需认证的存活探针。

然后在浏览器中打开 claude.ai：Customize → Connectors → Add custom connector，URL 为 https://your-app.up.railway.app/mcp/<secret>。

工具

网络 — transit_list_operators、transit_list_lines、transit_find_stops

实时 — transit_next_departures、transit_list_vehicles

警报 — transit_list_service_alerts

每个工具都接受 response_format: "markdown" | "json"。默认是 Markdown，针对 LLM 阅读进行了优化；JSON 是完整的结构化负载。无论格式如何，structuredContent 始终会被填充。

示例

“下一班 N Judah 是什么时候？” → 使用 operator_id="SF" 和 query="judah" 调用 transit_find_stops 获取站点代码，然后使用该代码和 line="N" 调用 transit_next_departures。

“BART 运行正常吗？” → 使用 operator_id="BA" 调用 transit_list_service_alerts。

“我的通勤路上有什么问题吗？” → 不带运营机构调用 transit_list_service_alerts——一次调用即可覆盖所有湾区机构。

“现在火车在哪里？” → 使用 operator_id="BA" 调用 transit_list_vehicles。

设计说明

天生只读。 511 不提供任何写端点，每个工具都带有 readOnlyHint: true。测试对此进行了断言。

每个端点映射一个 operator_id。 511 在其静态端点上将此参数称为 operator_id，在其实时端点上称为 agency，但值相同。这里的每个工具都接受 operator_id，客户端会进行映射。这种分裂是 511 的问题，而不是调用方的问题。

两个实时端点确实有不同的封装结构。 StopMonitoring 没有 Siri 根包装；VehicleMonitoring 有。已发布的规范显示两者都有——但规范是错误的，按照文档中的结构解析发车信息将一无所获。两者都按照实时 API 实际输出的方式进行解析，并有测试分别固定。

倒计时基于到达时间，而非发车时间。 在几乎每一行真实数据中，ExpectedDepartureTime 都是 null，因此基于它进行倒计时会显示一个没有服务的站点。ExpectedArrivalTime 才是可靠的字段。

解析前会去除 UTF-8 BOM。 511 在 JSON 正文前加上 U+FEFF，这会导致简单的 JSON.parse 在完全有效的负载上抛出异常。认证失败是纯文本且没有 BOM，因此去除操作在状态检查之后进行。

看似数字和布尔值的值往往并非如此。 坐标和方位角以 JSON 字符串形式到达，VehicleAtStop 是字符串 "false"，并且在整个数据中使用 "" 表示 null。盲目强制转换会将缺失的位置变成看似有效的 0,0（非洲海岸外），因此空字符串被视为缺失而非零。

纪元零哨兵不是时间戳。 已排定但未分配车辆的行程会报告 RecordedAtTime 为 1970-01-01T00:00:00Z。它显示为“尚未分配车辆”，而不是“记录于 56 年前”。

GTFS-Realtime 枚举被解码。 511 的 JSON 警报渲染输出 "effect": 3，而 XML 渲染则显示 SignificantDelays。原因和影响都被映射回文字。

511 内部的伪机构被过滤掉。 5E、5F、5O 和 5S 分别是 511 应急、翻牌标志、运营和员工——它们出现在运营机构列表中，但不携带任何服务数据。

一切都使用太平洋时间。 时间戳以 UTC 到达，并以 America/Los_Angeles 渲染，因此夏令时在这里处理一次，而不是由模型每年处理两次。请注意，511 自己的 TimeZone 字段为每个湾区机构报告 America/Vancouver——这是一个已知的上游数据错误，被有意忽略。

截断总是被明确说明。 511 不进行分页；它返回整个集合，而大型机构有数千个站点。工具接受客户端 limit，每个被截断的结果都会说明省略了多少，因为静默缩短的列表会被理解为“这就是全部”。

注意事项

  • 每小时配额为所有端点共 60 次请求。这是任何工作流的硬性限制。

  • 运营机构代码容易猜错：VTA 是 SC（不是 VT），Capitol Corridor 是 AM（不是 CC），Tri Delta 是 3D。transit_list_operators 会在其输出中打印这些陷阱。

  • 站点代码属于一个运营机构，不能在不同机构之间互换。

  • transit_find_stops 在此服务器上进行过滤，因此窄查询不会节省配额——无论如何都会获取完整的站点列表。

  • 实时预测大约提前 90 分钟，511 会从发车信息源中省略线路的最终仅到达站点。

  • tripupdates 和 vehiclepositions 仅支持 protobuf，没有 JSON 选项，因此有意不暴露它们——支持它们意味着为 SIRI 端点已覆盖的数据引入 protobuf 依赖。

项目结构

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # enums, limits, operator-code traps
├── types.ts               # interfaces for every 511 entity
├── services/
│   └── transit-client.ts  # fetch wrapper, auth, BOM stripping, quota tracking, errors
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # limiting, truncation, Pacific-time rendering
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── network.ts         # operators, lines, stops
    ├── departures.ts      # real-time arrivals and vehicles
    └── alerts.ts          # service alerts

测试

npm run build
npm test            # 42 checks: handshake, BOM, envelopes, quirks, errors (mocked API)
npm run test:http   # 17 checks: config validation, path-secret gating, method handling, origins

两个测试套件都针对本地模拟运行，该模拟故意重现 511 的真实怪癖——BOM、缺失的 Siri 包装、字符串化的布尔值和坐标、纪元哨兵以及纯文本错误正文——因为这些正是简单客户端容易出错的地方。

Available Tools

6 tools
transit_find_stopsFind Transit StopsA
Read-onlyIdempotent

Find an agency's stops by name, and get the stop codes the real-time tools need.

This is the bridge between "Downtown Berkeley" and the code transit_next_departures wants. Pass a query: a large agency has thousands of stops, and 511 returns all of them in one unpaginated response.

Args:

  • operator_id (string): agency code from transit_list_operators

  • query (string): substring match on the stop name — strongly recommended

  • limit (number): maximum stops to return (default: 25)

  • response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "total": number, "truncated": boolean, "stops": [ { "id": string, "Name": string, "Location": { "Latitude": string, "Longitude": string } } ] }

Examples:

  • "When's the next train from Downtown Berkeley?" -> operator_id='BA', query='downtown berkeley', then pass the id to transit_next_departures

  • "Find Muni stops on Judah" -> operator_id='SF', query='judah'

  • Don't use when: you already have the stop code

Error Handling:

  • Stop codes belong to ONE operator and are not interchangeable between agencies

  • Filtering happens on this server, so a narrow query does not save quota — the full list is fetched either way

  • 511 allows 60 requests per hour across ALL endpoints

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (max 200)
queryNoCase-insensitive substring match on the stop name. Strongly recommended — a large agency has thousands of stops
operator_idYesOperator code from transit_list_operators, e.g. 'BA' for BART, 'SF' for Muni
response_formatNoOutput format: 'markdown' for human-readable, 'json' for machine-readablemarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
stopsYes
totalYes
truncatedYes

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior: server-side filtering (no quota savings), unpaginated response from 511, and the 60-request/hour rate limit. It also clarifies that stop codes are operator-specific—valuable context beyond 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 longer but well-structured with clear sections (Args, Returns, Examples, Error Handling). Each section contributes distinct value: the main purpose is front-loaded, examples are concise, and error handling is pertinent. No fluff or 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?

The description is fully self-contained: it includes the return object structure, examples mapping to actual operator IDs, error-handling notes, rate limits, and the relationship to sibling tools. With an output schema present and annotations covering safety, nothing an agent needs to invoke correctly is missing.

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 description coverage is 100%, so the baseline is 3. The description's Args section largely repeats schema descriptions (e.g., 'operator_id' from transit_list_operators, 'query' substring match and 'strongly recommended'). It adds no new per-parameter semantics; the 'strongly recommended' phrasing already appears in the schema. The unpaginated response note is behavioral, not parameter-specific.

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 identifies the tool's purpose: 'Find an agency's stops by name, and get the stop codes the real-time tools need.' It explicitly ties the tool to transit_next_departures, distinguishing it from other transitive tools. The purpose is specific and actionable.

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?

The description provides explicit usage context: 'This is the bridge between "Downtown Berkeley" and the code transit_next_departures wants.' It also states a clear when-not: 'Don't use when: you already have the stop code.' Examples illustrate typical queries, making the intended conditions unambiguous.

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

transit_list_linesList Transit LinesA
Read-onlyIdempotent

List an agency's routes.

Use this to resolve a line name a user mentions into the id the real-time tools filter on, or to answer "what routes does this agency run".

Args:

  • operator_id (string): agency code from transit_list_operators

  • query (string): substring match on the line name or public code

  • limit (number): maximum lines to return (default: 25)

  • response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "total": number, "truncated": boolean, "lines": [ { "Id": string, "Name": string, "PublicCode": string, "TransportMode": string, "Monitored": boolean } ] }

Examples:

  • "What BART lines are there?" -> operator_id='BA'

  • "Is there an N line on Muni?" -> operator_id='SF', query='N'

  • Don't use when: you want stops on a line (use transit_find_stops)

Error Handling:

  • A large agency returns many lines; use query to narrow rather than raising limit

  • 511 allows 60 requests per hour across ALL endpoints

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (max 200)
queryNoCase-insensitive substring match on the line name or public code
operator_idYesOperator code from transit_list_operators, e.g. 'BA' for BART, 'SF' for Muni
response_formatNoOutput format: 'markdown' for human-readable, 'json' for machine-readablemarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
linesYes
totalYes
truncatedYes

TDQS

A4.7/5.0
Behavior5/5

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

The annotations already declare readOnly, idempotent, and non-destructive hints. The description goes further by disclosing the response shape, the truncation flag, the possibility of many results for large agencies, and the 60-request-per-hour rate limit across all endpoints. This adds behavioral context beyond the annotations and contradicts nothing.

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 well-organized with clear sections (Summary, Args, Returns, Examples, Error Handling). It front-loads the purpose and usage, and every sentence adds value—examples, exclusions, rate limits, and return format. Despite covering many aspects, it remains concise and skimmable.

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?

The tool has 4 parameters, an output schema, and sits among 5 siblings. The description covers all essentials: purpose, parameter examples, return structure, error handling, and even the rate limit. There is nothing an agent needs to know to call this correctly that is missing, and the output schema already documents the return shape.

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?

The schema covers all parameters with detailed descriptions (100% coverage), so the description does not need to duplicate that. It adds a few examples (operator_id='BA', 'SF') and clarifies that query is a case-insensitive substring, but these are minor enhancements. The baseline of 3 is appropriate because the schema already carries the main semantic load.

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 ('List') and resource ('an agency's routes'), and immediately explains its practical use (resolving a line name into an id, answering route questions). It explicitly distinguishes itself from a sibling tool ('Don't use when: you want stops on a line (use transit_find_stops)'), which is a clear differentiation.

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?

It gives explicit 'Use this to...' guidance and an explicit 'Don't use when...' with a named alternative. Examples illustrate common queries, and the error handling section advises when to prefer query narrowing over raising limit. This leaves no ambiguity about when to invoke this tool.

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

transit_list_operatorsList Transit OperatorsA
Read-onlyIdempotent

List Bay Area transit agencies and their operator codes.

Start here. Every other tool needs an operator code, and this is what produces them — BART is 'BA', Muni is 'SF', AC Transit is 'AC', Caltrain is 'CT'.

The Monitored flag matters: agencies reporting real-time data support live departures and vehicle positions, while schedule-only agencies do not.

Args:

  • monitored_only (boolean): only agencies publishing real-time data (default: false)

  • limit (number): maximum operators to return (default: 50)

  • response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "total": number, "truncated": boolean, "operators": [ { "Id": string, "Name": string, "Monitored": boolean, "PrimaryMode": string, "TimeZone": string } ] }

Examples:

  • "What transit agencies are there?" -> call with no arguments

  • "Which ones have live tracking?" -> monitored_only=true

  • Call this first whenever the user names an agency, to resolve its code

Error Handling:

  • Ignore the TimeZone field: 511 reports "America/Vancouver" for every Bay Area agency, which is a known upstream data bug. Everything here is Pacific time

  • 511-internal pseudo-agencies (5E, 5F, 5O, 5S) are filtered out — they carry no service data

  • 511 allows 60 requests per hour across ALL endpoints, so cache this rather than re-fetching

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (max 200)
monitored_onlyNoOnly agencies that publish real-time data, excluding schedule-only ones
response_formatNoOutput format: 'markdown' for human-readable, 'json' for machine-readablemarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
totalYes
operatorsYes
truncatedYes

TDQS

A4.9/5.0
Behavior5/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. The description adds substantial behavioral context beyond those: the Monitored flag semantics, the known TimeZone bug (inaccurate 'America/Vancouver' values), the filtering of pseudo-agencies (5E, 5F, 5O, 5S), and the rate limit (60 req/hour across all endpoints) with caching advice. This is exactly the kind of operational detail an agent needs and the annotations do not provide.

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 thorough but efficiently organized into clear sections (Args, Returns, Examples, Error Handling). Every sentence adds value: the opening line is the purpose, the 'Start here' directive is front-loaded, examples are concise, and error handling covers real-world quirks. No redundancy or filler—each element earns its place.

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 tool with 3 optional parameters and an output schema, the description covers everything needed to call it correctly: it provides default values, return shape (matching the output schema), examples, and critical edge cases (TimeZone bug, filtering, rate limit). Even though the output schema exists, the description's inclusion of the return shape is redundant but not harmful; the error-handling notes are essential and not available anywhere else. The description is fully sufficient for an agent to use this tool without surprises.

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 baseline is 3. The description goes beyond the schema by explaining the semantic impact of monitored_only (supports live departures/vehicle positions vs schedule-only), giving concrete usage examples for each parameter, and clarifying the response_format default. It also mentions the default for limit in prose. While the schema already has descriptions, the description adds contextual meaning that helps an agent decide parameter values appropriately.

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 opens with a clear verb-resource pair: "List Bay Area transit agencies and their operator codes." It immediately differentiates from siblings by noting "Every other tool needs an operator code, and this is what produces them," which is unique among the sibling tools. The specific examples (BART='BA', Muni='SF') further cement the purpose.

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?

Explicitly instructs when to use: "Start here." and "Call this first whenever the user names an agency, to resolve its code." It also explains the monitored_only flag's relevance for choosing between live vs schedule-only agencies, effectively guiding the agent on when to apply different parameter values. No alternatives are named, but the tool is clearly positioned as the entry point, so exclusion guidance is unnecessary.

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

transit_list_service_alertsList Transit Service AlertsA
Read-onlyIdempotent

Service alerts — delays, outages, detours and planned disruptions.

Answers "is BART running normally", "why is my line delayed" and "anything I should know before I leave". Omit operator_id to sweep every Bay Area agency in a single request, which is also the kinder option against the hourly quota.

Args:

  • operator_id (string): limit to one agency; omit for all operators

  • query (string): substring match on the headline or description

  • active_only (boolean): only alerts whose active period covers now (default: true)

  • limit (number): maximum alerts to return (default: 25)

  • response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "total": number, "truncated": boolean, "alerts": [ { "id": string, "header": string, "description": string, "effect": string, "cause": string, "routes": [string], "start": number, "end": number } ] // epoch SECONDS }

Examples:

  • "Any BART delays?" -> operator_id='BA'

  • "Anything wrong on my commute?" -> omit operator_id, read across agencies

  • "Weekend track work?" -> active_only=false, query='weekend'

  • Don't use when: you want a specific stop's arrivals (use transit_next_departures)

Error Handling:

  • No alerts is genuinely good news, not an error — it means normal service

  • Timestamps here are epoch seconds, unlike the ISO strings elsewhere in this API

  • Setting active_only=false surfaces future planned work as well as current problems

  • 511 allows 60 requests per hour across ALL endpoints

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (max 200)
queryNoCase-insensitive substring match on the alert headline or description
active_onlyNoOnly alerts whose active period covers now
operator_idNoLimit to one agency; omit for alerts across every Bay Area operator
response_formatNoOutput format: 'markdown' for human-readable, 'json' for machine-readablemarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
totalYes
alertsYes
truncatedYes

TDQS

A5/5.0
Behavior5/5

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

Annotations only indicate read-only, idempotent, and non-destructive behavior. The description adds crucial behavioral nuance: no alerts means normal service (not an error), timestamps are epoch seconds unlike the ISO strings in other API endpoints, active_only=false surfaces future planned work, and rate limits. This goes well beyond 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?

Structured with Args, Returns, Examples, and Error Handling sections. The purpose and primary use cases are front-loaded in the first sentence, and every sentence adds value—examples, rate limits, or format distinctions. No redundancy or fluff.

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?

The output schema is present and the description includes a return format example with field types. It covers error handling (no alerts ≠ error), rate limits, timestamp format, and sibling routing. For a 5-parameter tool with no required parameters, this is fully complete for an agent.

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 100%, so the baseline is 3, but the description adds substantial meaning: operator_id omission sweeps all agencies and is 'kinder' against quota, active_only=false is tied to 'weekend track work' examples, and query is illustrated with a practical use case. These contextual insights help an agent choose parameter values 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 states a specific verb ('List') and resource ('Transit Service Alerts'), and grounds it with concrete questions it answers ('is BART running normally', 'why is my line delayed'). It explicitly differentiates from the sibling transit_next_departures by naming when not to use it, making the purpose unmistakable.

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?

Explicitly states when to use the tool (answering delay/outage questions) and when not to ('Don't use when: you want a specific stop's arrivals (use transit_next_departures)'). Also gives operational guidance, such as omitting operator_id to sweep all agencies and conserve quota—practical context an agent needs.

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

transit_list_vehiclesList Transit Vehicle PositionsA
Read-onlyIdempotent

Live positions of an agency's vehicles currently in service.

Answers "where are the trains right now" and "how many buses are running on this line". For "when does one get to me", use transit_next_departures instead.

Args:

  • operator_id (string): agency code from transit_list_operators

  • line (string): only vehicles on this line, matched on name or id

  • limit (number): maximum vehicles to return (default: 25)

  • response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "total": number, "truncated": boolean, "vehicles": [ { "line": string, "vehicle": string, "destination": string, "latitude": number | null, "longitude": number | null, "bearing": number | null, "recorded_at": string } ] }

Examples:

  • "How many Muni trains are running on the N?" -> operator_id='SF', line='N'

  • "Where are the BART trains?" -> operator_id='BA'

  • Don't use when: you want arrival times at a stop (use transit_next_departures)

Error Handling:

  • Coordinates arrive as strings and may be empty; those vehicles report "position unavailable" rather than a false 0,0

  • An agency with no real-time feed returns nothing — check Monitored in transit_list_operators

  • 511 allows 60 requests per hour across ALL endpoints

ParametersJSON Schema
NameRequiredDescriptionDefault
lineNoOnly vehicles on this line
limitNoMaximum results to return (max 200)
operator_idYesOperator code from transit_list_operators, e.g. 'BA' for BART, 'SF' for Muni
response_formatNoOutput format: 'markdown' for human-readable, 'json' for machine-readablemarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
totalYes
vehiclesYes
truncatedYes

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already signal read-only, idempotent, and open-world behavior. The description adds valuable, non-obvious behavioral details: coordinates arrive as strings and may be empty, agencies with no real-time feed return nothing (with a pointer to check 'Monitored'), and a 60-requests-per-hour rate limit. This goes well beyond the annotations and prepares the agent for realistic edge cases.

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?

The description is longer than strictly necessary because it repeats the Args and Returns sections that already exist in the schema. However, it is well-structured with clear sections (purpose, args, returns, examples, error handling) and the most important guidance (purpose and alternative) is front-loaded. Every section adds unique value (examples, error handling, rate limits), so the length is justified despite some 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?

For a list tool with an output schema and read-only annotations, the description covers all essential context: proper use cases, alternatives, parameter semantics, edge cases (missing coordinates, empty feeds, rate limits), and concrete examples. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so the schema fully documents each parameter. The description adds some meaning beyond that: it clarifies that 'line' matches on name or id, and provides concrete examples (operator_id='SF', line='N') that illustrate how parameters map to real queries. Defaults for limit and response_format are repeated, but the examples and matching detail provide modest added value.

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 opens with a clear, specific statement of what the tool does: 'Live positions of an agency's vehicles currently in service.' It names the resource (vehicles) and action (list positions), and explicitly differentiates from a sibling tool ('For "when does one get to me", use transit_next_departures instead'), so an agent can distinguish it without opening schemas.

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?

Provides explicit when-to-use guidance: answers 'where are the trains right now' and 'how many buses are running on this line', and gives a direct exclusion: 'Don't use when: you want arrival times at a stop' with the alternative named. Examples reinforce correct usage and operator/line selection.

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

transit_next_departuresNext Transit DeparturesA
Read-onlyIdempotent

Live arrival predictions for the next vehicles at a stop.

This is the tool for "when is my next train/bus". It returns real-time predictions, not the printed timetable, and reports minutes-from-now alongside Pacific clock time.

Args:

  • operator_id (string): agency code from transit_list_operators, e.g. 'BA', 'SF'

  • stop_code (string): stop code from transit_find_stops. Codes belong to ONE operator and are not interchangeable between agencies

  • line (string): only departures on this line, matched on name or id

  • limit (number): maximum departures to return (default: 10)

  • response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "total": number, "truncated": boolean, "operator": string, "stop_code": string, "stop_name": string, "retrieved_at": string, "departures": [ { "line": string, "destination": string, "expected": string, "aimed": string, "minutes": number, "vehicle": string | null, "at_stop": boolean } ] }

Examples:

  • "When's the next N Judah?" -> operator_id='SF', stop_code from transit_find_stops, line='N'

  • "Next BART from Downtown Berkeley?" -> operator_id='BA', the stop's code

  • Don't use when: you want the scheduled timetable rather than live predictions

Error Handling:

  • An empty result usually means service has ended for the night, or the stop is a route's final stop — 511 omits arrival-only terminals from this feed

  • Predictions extend roughly 90 minutes ahead; nothing beyond that appears

  • Rows reading "scheduled only, no live prediction" have no vehicle assigned yet

  • 511 allows 60 requests per hour across ALL endpoints — never poll this in a loop

ParametersJSON Schema
NameRequiredDescriptionDefault
lineNoOnly departures on this line, matched against the line name or id
limitNoMaximum results to return (max 200)
stop_codeYesStop code from transit_find_stops. Codes are specific to one operator
operator_idYesOperator code from transit_list_operators, e.g. 'BA' for BART, 'SF' for Muni
response_formatNoOutput format: 'markdown' for human-readable, 'json' for machine-readablemarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
totalYes
operatorNo
stop_codeNo
stop_nameNo
truncatedYes
departuresYes
retrieved_atNo

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds substantial behavioral context: real-time vs static, minutes-from-now plus Pacific clock time, 'scheduled only' rows, a 90-minute prediction horizon, empty results meaning (end of service or arrival-only terminal), and a 60-requests-per-hour rate limit. This goes far beyond the annotations, providing critical operational details an agent needs to interpret results and avoid misuse.

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?

Structured with clear sections (Purpose, Args, Returns, Examples, Error Handling) and front-loaded with the core purpose. Every sentence adds value; error handling is critical for correct agent behavior. It is detailed but not flabby — the length is justified by the operational caveats and edge cases.

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 tool with 5 parameters and an output schema, the description covers all essential usage aspects: parameter semantics, error scenarios (empty results, truncated predictions), time horizon, rate limits, and a full output structure in the Returns section. Even though an output schema is provided, the description's explicit sample JSON and explanation of fields further aid the agent. Nothing needed for correct invocation is missing.

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?

Even though schema coverage is 100%, the description enriches every parameter: it provides real examples (operator_id 'BA'/'SF', stop_code from transit_find_stops), warns that stop codes are operator-specific and not interchangeable, clarifies line matching ('matched on name or id'), and explains response_format options. The Args section adds value beyond the schema's terse descriptions, especially for stop_code and line.

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?

Description states a specific verb and resource: 'Live arrival predictions for the next vehicles at a stop' and explicitly positions it as 'the tool for when is my next train/bus'. It distinguishes from the printed timetable and clarifies scope (real-time, not static), making it clearly different from sibling tools that list operators, stops, lines, vehicles, or alerts.

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?

Provides explicit when-to-use guidance via examples ('When's the next N Judah?' maps to specific parameters), an explicit 'Don't use when' exclusion for scheduled timetable, and references prerequisite tools (transit_list_operators, transit_find_stops) for parameter sourcing. It also includes rate-limit guidance ('never poll this in a loop'), which is directly relevant to usage.

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. 6 tool updatesv1.0.0
    • First observedtransit_find_stops
    • First observedtransit_list_lines
    • First observedtransit_list_operators
    • First observedtransit_list_service_alerts
    • First observedtransit_list_vehicles
    • First observedtransit_next_departures
Deploy Server
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

TDQS

A4.8/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct resource: operators, lines, stops, departures, vehicles, and alerts. Descriptions explicitly cross-reference when to use which (e.g., 'Don't use when' sections), eliminating ambiguity. No two tools overlap in purpose.

Naming Consistency5/5

All tools share the 'transit_' prefix and follow a consistent verb-object pattern: list_operators, list_lines, find_stops, next_departures, list_vehicles, list_service_alerts. Minor variation between 'list', 'find', and 'next' but the style is uniform and predictable.

Tool Count5/5

Six tools are well-scoped for a transit information server, covering discovery (operators, lines, stops), real-time queries (departures, vehicles), and alerts. No tool is redundant, and the count feels neither sparse nor bloated.

Completeness4/5

The tool surface covers the full workflow of querying transit info: discover agencies, lines, stops, then get live departures, vehicle positions, and alerts. A minor gap is the lack of a dedicated scheduled timetable tool, though the departures endpoint includes aimed times. Overall, the domain is well covered.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers