search_nearby_bus_stops

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It conveys that the search is read-only and that an 'estimated' service threshold is involved, but it does not explain how 'nearby' is measured, whether results are limited, which service day is used, or how the daily-service threshold is applied. This leaves important behavioral traits undisclosed.

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 a single focused sentence with no filler or redundant restatement of the tool name. The core action is front-loaded ('Find nearby stops') and the distinguishing filter is appended concisely. Every word contributes.

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 read-only search tool with an output schema and self-explanatory parameter names, the description is minimally adequate. However, it fails to clarify the meaning of the filtering threshold, how walking distance factors into 'nearby', or the relevance of service_day. An agent could invoke it correctly using the schema, but would still be guessing about intended usage semantics.

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 by explaining parameters, but it does not. 'Daily-service threshold' loosely maps to minimum_daily_trips, and 'nearby' maps to max_walk_minutes, but the required latitude/longitude and the optional service_day are not mentioned at all. The description adds minimal semantic value over the parameter names.

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 uses a clear verb and resource: 'Find nearby stops' and adds a specific filtering criterion ('meeting an estimated daily-service threshold'). It is distinguishable from sibling tools like search_nearby_hospitals and search_nearby_markets because of the 'stops' subject, though 'stops' is slightly ambiguous without the tool name and no sibling is named explicitly.

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 implies the tool is for finding transit stops near a location, but it does not state when to use it versus alternatives, nor does it provide any exclusion criteria. Since the sibling tools cover clearly different resource types (hospitals, markets, neighborhoods, demographics), the lack of explicit routing is less harmful, but guidance is still only implied.

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