nj-transit-mcp

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

Annotations already declare readOnlyHint, destructiveHint=false, openWorldHint and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful data traits beyond that: bus feed long names are empty and trip headsigns must be used for destinations, and the per-system route counts set expectations for result volume. It stops short of stating whether system filters reduce the result or how results are ordered.

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

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

Four short, front-loaded sentences, each carrying concrete information (counts, the bus short_name caveat, PATH scope) with no filler. Line-broken formatting is slightly awkward but does not impede scanning.

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

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

An output schema exists and annotations cover safety, so return-value detail is rightly omitted. The remaining gap is the system parameter's accepted values and the relationship between the enumerated systems and that filter, which the description only hints at.

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

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

There is one parameter ('system') with 0% schema description coverage and only a default of 'all'. The description partially compensates by naming the three systems (NJ Transit, NJ bus, PATH), which implies the accepted filter values, but it never states that these are the values for the system parameter or what an invalid value does.

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

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

The title supplies the verb ('List all routes') and the description states the resource precisely: all lines/routes across NJ Transit rail/light-rail, NJ bus, and PATH, with route counts. Sibling tools (next_departures, trip_between, etc.) are clearly different operations, so no sibling differentiation is needed. The description text itself never states the verb, relying on the title.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as search_stations when the caller only needs one route. The enumeration is implicitly the lookup step for route IDs, but that is left to inference.

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

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

Beyond the readOnly/openWorld annotations, it discloses real operational traits: live data requires NJT credentials, bus live data is unavailable in v1.2, PATH needs no key, and all times are America/New_York. This is substantive context the annotations cannot convey, though it doesn't discuss pagination or what happens when a station is ambiguous.

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

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

It is front-loaded with the core action and then groups per-system behavior compactly. The trailing NOTE earns its place by preventing a plausible wrong assumption (that NJT has a subway), though the serviceability of the block format is slightly repetitive with the per-system lines.

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

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

With an output schema present, return values need not be described, and the system/credential/timezone context is rich. The remaining gap is the three undocumented optional parameters (line, limit, towards), which leave filtering behavior underspecified for a tool with 0% schema description coverage.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. It does explain 'station' (name or stop ID) and 'system' (three enumerated values with semantics), but 'line', 'limit', and 'towards' are left entirely undocumented, so the agent must guess at their format and filtering behavior.

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

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

The description names a specific verb+resource ("next departures from a station/stop") and immediately scopes it across three transit systems, making it clearly distinct from siblings like trip_between, service_alerts, and search_stations. An agent can identify the tool's role without opening the schema.

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

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

It explicitly routes between system values: 'nj_transit' for rail/light rail with live-versus-scheduled behavior, 'nj_bus' for scheduled-only bus, and 'path' for live arrivals with no key. It even warns there is no NJ subway and directs subway-like use to 'path' or HBLR/NLR/River Line, which is exactly the when-to-use guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, but the description adds a meaningful operational detail: an 'all' search may download a 50 MB bus GTFS once. It also explains that the tool returns station/stop IDs for use with next_departures and trip_between, which is useful 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.

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

The description is front-loaded with the core action and then explains the system choices and download caveat without unnecessary wording. Every sentence contributes either selection guidance or operational context.

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

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

For a two-parameter lookup tool with an output schema, the description covers the key behavioral caveat and parameter meanings well. It could be slightly more complete by describing query matching behavior, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that query searches by name and fully defines the system values ('nj_transit', 'nj_bus', 'path', 'all'), including the default behavior of 'all', though it does not specify matching semantics such as substring or case sensitivity.

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

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

States a specific verb and resource: 'Find stations/stops by name.' It also distinguishes the supported transit systems and ties the result IDs to downstream tools next_departures and trip_between, making its role clear among siblings.

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

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

Gives clear selection guidance for the system parameter, including the important caveat that system='all' includes bus and triggers a one-time 50 MB GTFS download. It also tells the agent to use system='nj_bus' for bus-only searches and mentions downstream tools, though it does not explicitly state when not to use this tool versus lines or service_alerts.

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

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

The annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false); the description adds the useful fact that the result is a metadata snapshot about the server's own data state, not a transit answer. It also enumerates the content dimensions (range, counts, live flag, feed age), though it does not mention whether the snapshot can be stale itself.

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

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

Two sentences, with the content inventory first and the decision rule second. The quoted question makes the intended use concrete without padding.

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

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

With zero parameters, an output schema, and annotations that declare it a read-only, open-world call, the description gives everything an agent needs to decide when to call this tool instead of a departure or alert query.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing for the description to clarify and no mismatch to flag. It does not waste words restating a nonexistent input.

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

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

The description names the concrete contents the tool reports: 'GTFS date range and counts, whether live NJ data is enabled, PATH feed age.' That is far more specific than a tautology, and the 'live or scheduled' framing tells it apart from the query siblings passing through the same domain.

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

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

'Use this to answer "is this live or scheduled?" honestly' gives a clear routing condition: call it when you need to validate data provenance before trusting a departure answer. No explicit when-not or sibling alternatives are named, which keeps it short of a 5.

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

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

Annotations already cover read-only and non-destructive behavior, so the description's job is to add operational context — and it does: NJT needs credentials configured, and PATH alerts are returned as explicitly unavailable rather than fabricated, which is important for interpreting results correctly. It stops short of describing rate limits or freshness/caching of alert data.

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

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

Two sentences with no filler in the parenthetical caveats, but the leading "Service alerts." duplicates the title and burns the highest-value position on a restatement rather than on what the tool does. The dense credential/PATH caveat is packed into one overlong sentence.

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

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

An output schema exists, so return-value detail is not needed, and the credential and PATH-unavailable caveats cover the main failure modes. What's missing is the parameter's value space and a plain statement of what an 'alert' record contains — enough gaps that an agent could call it but might not know what to pass for 'system'.

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

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

The single 'system' parameter has 0% schema description coverage and no enum, so the description must carry the load. It names systems in prose but never ties them to the parameter, never states the accepted values (e.g., njt/path/all) despite the 'all' default, and never says whether unknown values error out.

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

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

The description opens by restating the title ("Service alerts") and never states a verb or what the tool actually returns for a given system. It does narrow scope by naming the two systems (NJ Transit, PATH) and their coverage differences, but an agent must infer that this fetches current disruption notices rather than, say, configuring alerts.

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

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

The NJT credential prerequisite and the pointer to server_status for enabling it give genuine when-to-use context. However, there is no guidance on when to choose this over siblings like lines, next_departures, or trip_between, and no statement of when this tool should be skipped entirely.

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

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

Beyond the annotations, it discloses important behavior: same-trip/no-transfer results, ET times, and that nj_bus is scheduled only in v1.2. It does not explain limit/pagination behavior or how to resolve station identifiers, but the annotations already cover the safety profile.

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

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

The description is compact and front-loaded with the core purpose. Each sentence adds practical detail about same-trip behavior, return fields, time zone, and system options without waste.

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

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

With an output schema present, the description does not need to fully document return fields, though it helpfully summarizes them. It is nearly complete for invocation, but it omits guidance on station identifier format and the limit parameter.

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

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

Schema description coverage is 0%, so the description carries the burden. It adds useful meaning for system values and defaults and implies that origin/destination are stations, but it leaves the limit parameter entirely unexplained and gives no station identifier format.

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

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

The description states a specific resource and operation: next NJ Transit trains/buses from origin to destination on the same trip, with no transfers. It is clear enough to distinguish from a generic departures tool, but it does not explicitly name or contrast with the sibling next_departures.

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

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

It gives clear usage context: same-trip only, no transfers, and bus results are scheduled only in v1.2. It does not explicitly route the agent to alternatives such as next_departures or search_stations, so it stops short of full when/when-not guidance.

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