stl_gtfs_schema

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

The description does not contradict the readOnlyHint/idempotentHint annotations, and it correctly implies a read-only inspection. However, it adds no extra behavioral context beyond the annotations, such as potential cost of retrieving sample values for large tables or any side effects (though none exist).

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 extremely concise, using a single sentence to convey the tool's purpose and a brief parameter explanation. No superfluous words or redundant phrasing, making it easy to scan.

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?

Although the description lists the kinds of output (columns, null rates, etc.), it does not explain the output schema structure or how the snapshot parameter affects results. For a tool with an output schema, this lack of detail leaves the agent uncertain about the exact return format and the role of snapshot.

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 description explains the 'table' parameter with examples but leaves the 'snapshot' parameter entirely undocumented. With schema coverage at 0% and only one of two parameters described, the description fails to compensate for the missing snapshot semantics, which is a significant gap.

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 clearly indicates the tool provides schema information (columns, null rates, distinct counts, sample values) for a single GTFS file/table. It distinguishes itself from sibling tools like stl_gtfs_files or stl_gtfs_stats by focusing on schema details, though the verb is implicit rather than explicit.

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?

No guidance is given on when to use this tool versus alternatives like stl_gtfs_query or stl_gtfs_stats. It does not mention typical use cases, such as inspecting a table's structure before querying, or scenarios where the snapshot parameter would be needed.

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