SF Bay Area Transit MCP

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds real value by disclosing that the call performs no upstream routing contact and by enumerating what the response contains, which matters because no output schema exists.

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?

A single sentence with zero filler, leading with the read operation and then listing the returned items. Nothing would be gained by trimming or reordering it.

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 zero-parameter, read-only metadata tool with rich annotations, the description covers purpose and return contents adequately. It stops short of detailing the structure or units of the returned limits and data-source lists, which is a minor gap given the absence of an output schema.

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 zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-related claims are made or needed.

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 with a specific verb ("Read") and enumerates the exact resources returned: current time, available tools, data sources, and service limits. The phrase "without contacting a routing service" implicitly separates it from routing siblings like plan_trip, though it never names an alternative outright.

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?

Usage is only implied: an agent can infer this is the cheap metadata/introspection call to make before or instead of routing calls. There is no explicit when-to-use statement, no prerequisites, and no named alternative among get_stop_departures, plan_trip, or search_places.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description adds genuinely new behavior: data is sent to a named third party (Transitous) with stop ID and time, and no API key is required — a data-egress and auth disclosure that annotations cannot express. It stops short of describing fallback behavior when live predictions are unavailable.

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 sentences, front-loaded with the capability and ending with terse operational facts (Transitous, no API key). Nearly every clause earns its place; only the trailing "Omit departureTime for now" is under-specified rather than merely brief.

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?

There is no output schema, so the description usefully enumerates the return categories (live vs. scheduled times, cancellations, boarding restrictions) in place of one. For a nested-parameter read tool it is close to sufficient, with the undocumented `limit` and the ambiguous departureTime note as the remaining holes.

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% across three parameters including a nested stop object, so the description must carry the load. It does explain where stopId and the coordinates come from and gestures at departureTime, but it never mentions the nested `label` field or the `limit` parameter (default 10, max 20) at all, leaving a third of the surface undocumented in both schema and prose.

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 ("Show upcoming departures at a selected Bay Area transit stop") and enumerates what the payload contains: live predictions, scheduled times, cancellations, boarding restrictions. The Bay Area geographic scoping plus the pointer to search_places/plan_trip for the stop token separates it cleanly from the three 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 explicit prerequisite routing: obtain the stop ID and coordinates from a search_places STOP result or a plan_trip stop. That is real when-to-use guidance tied to named siblings. The one gap is "Omit departureTime for now," which reads as an incomplete caveat — an agent cannot tell whether the parameter is unsupported, ignored, or merely discouraged, so the exclusion is stated but not fully explained.

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/idempotent/openWorld annotations, the description discloses that coordinates are sent to a third party (Transitous), that no API key is needed, that transit trips bundle walking to and from stops, and that omitting times means a leave-now request. The data-sharing disclosure is exactly the kind of behavioral context annotations cannot express.

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 output content is front-loaded in the first sentence and every remaining sentence carries a distinct instruction. The style is telegraphic and slightly fragmented ('Use coordinates from the selected search result.'), which reads as clipped rather than as a coherent guide, but there is no filler.

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 8 parameters, nested coordinate objects, real geographic bounds, and no output schema, the description does the important work: it describes what a trip result contains and how to shape the time and mode inputs. The gap is the three undocumented optional parameters (limit, maxTransfers, wheelchair), which an agent must infer from names alone.

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 full explanatory burden. It does add real meaning for the time parameters (mutual exclusivity, mandatory UTC offset, default leave-now behavior) and for modes (walk/bicycle are alternatives to transit), but limit, maxTransfers, and especially the wheelchair accessibility flag are never mentioned despite being non-obvious to an agent.

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 with a specific verb and resource — 'Find complete trips' — and enumerates what a result contains (walking, transit, transfers, scheduled and predicted times, total travel time). It also implicitly positions itself against search_places by telling the agent to 'Use coordinates from the selected search result', so the agent can tell which sibling supplies its input.

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 explicit conditional guidance: omit times to leave now, otherwise supply departureTime OR arrivalTime with a UTC offset; add walk or bicycle to modes to compare non-transit options. That covers the primary decision points an agent faces when choosing how to call this versus other routing or lookup tools.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond those annotations: no API key is required, multiple matches return a list, and search text is sent to Transitous, which discloses a privacy/data-flow trait. It does not cover rate limits or error behavior, but the added context is substantive.

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 short, front-loaded with the core purpose, and each sentence adds useful information: search scope, disambiguation tip, return behavior, and data-flow disclosure. There is no redundant wording.

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 simple two-parameter search tool with no output schema and rich annotations, the description is largely complete. It explains the search scope, disambiguation behavior, multi-match return shape, and Transitous data flow. The main gap is that limit behavior is not described, but this is minor given the schema's default and maximum.

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 compensate for both parameters. It adds meaning for the query parameter by suggesting city inclusion for disambiguation, but it says nothing about the limit parameter, including its default of 5 or maximum of 10, and does not mention query length constraints. It only partially compensates for the schema's missing parameter descriptions.

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 matching Bay Area addresses, landmarks, or transit stops and their map coordinates." The scope is clear and distinct from sibling tools like get_stop_departures and plan_trip, though it does not explicitly name those alternatives.

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?

Provides a useful query-building guideline: including the city helps disambiguate same-named places. However, it gives no explicit guidance on when to use this tool versus plan_trip or get_stop_departures, so usage is only implied by the geocoding purpose.

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