md_transit_feeds

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

With annotations already declaring readOnlyHint=true, the description adds useful behavioral context by specifying output formats (ZIP archives with GTFS CSVs, protobuf) and the included modes. It does not cover rate limits or response structure, but for a parameterless URL lookup, this is adequate.

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 sentences, each delivering a distinct piece of information: purpose, static data format, modes, and real-time feed URLs. There is no redundancy or filler; the description is tightly written and front-loaded.

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?

Given that there is no output schema, the description covers the essential content: static schedule URLs, modes, and real-time feed URLs. It would benefit from a sample response structure, but the tool's simplicity means the description is reasonably complete for an agent.

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 has zero parameters, and schema coverage is 100% (vacuously), so the baseline is 4. The description appropriately avoids discussing parameters and focuses on the output, which is all that is 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 'Get Maryland MTA GTFS feed URLs for all transit modes,' naming the specific agency, resource type, and scope. It also enumerates the modes and differentiates static schedule downloads from real-time feed URLs, clearly distinguishing it from sibling tools like md_transit_vehicles or md_transit_trip_updates.

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 description makes it clear that this tool returns feed URLs rather than actual transit data, implying when it should be used (to obtain endpoints). However, it does not explicitly name alternative tools or provide exclusions, 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.