stl_report_handoff

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

Despite annotations already providing readOnlyHint, openWorldHint=false, idempotentHint, and destructiveHint=false, the description adds substantial behavior: every claim carries the snapshot id and date it was verified against, the warning about uncited facts silently becoming lies in a handoff doc, and the explicit list of sharp edges (24:xx encoding, DST arithmetic, stop_code vs stop_id, absent protobuf runtime, fares living off-feed). No annotation is contradicted. This is exactly the kind of context the 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 definition is front-loaded: first sentence states the deliverable, second states the artifact, third explains citations/re-verification, and the last enumerates concrete fallible areas. Each sentence earns its place with useful detail, though the final list of edge filters is a little heavy on the lowercase ('24:xx', 'stop_code vs stop_id') and could be trimmed without meaning change.

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 an output schema exists (so the return value needs no description), low parameter count, and safe/idempotent annotations, the description is nearly complete: it covers purpose, output nature, verification semantics, and the specific sharp edges that a consumer needs. Remaining gaps are the snapshot parameter semantics and an implicit alternative (stl_report_brief) which would firm up the boundary, both minor at this volume of single optional 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?

There is a single optional parameter, `snapshot`, and schema description coverage is 0%, so the description must compensate. It references 'the snapshot id... it was verified against', which hints at what the parameter concerns, but it never explains what value to pass, what omitting it means (e.g., latest snapshot), or any format constraints. The meaningful mentions keep it above a 2, but the parameter is realistically guesswork for 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 clearly states the output ('a markdown block... with citations' of 'verified facts about the feed') and the intended artifact ('Written for pasting into a CLAUDE.md handoff document'). It is easy to distinguish from the data-query siblings (stl_gtfs_*) and the brief (stl_report_brief seems the natural confusable), but it never explicitly names that sibling or defines how it differs, so it misses the fifth point.

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?

'Pending in a CLAUDE.md handoff document' gives a concrete, materially useful usage context that tells an agent exactly when this tool's output is needed, and the re-verification rationale implies the situation. It stops short of saying when not to use it, does not name alternatives such as stl_report_brief, and gives no conditional guidance, so it misses full when/when-not coverage.

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