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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it runs an Azure OpenAI call inside the server, makes no bus-details calls, tolerates an empty line, and only re-fetches the route when the search_context handoff is absent. It does not mention latency, token cost, or failure behavior of the LLM call.

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?

Front-loaded with the core action and kept to three dense sentences, with the search_context handoff highlighted. There is mild redundancy between 'from the search payload already fetched (no bus-details calls)' and the later statement that no second search is needed.

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?

An output schema exists, so return values need no explanation, and the description covers the call flow and dependency ordering well. For an 18-parameter tool, however, it leaves the input contract almost entirely undocumented, which is a meaningful completeness gap even if it is not the description's only job.

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 18 parameters, so the description must carry the burden and largely does not. It only illuminates search_context (the preferred handoff from search_buses); required inputs like trip_refs, cards, source, destination, date, and the many filter parameters are left entirely unexplained in both schema and description.

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 precise verb and resource: it builds one differentiating summary line per bus for the results card, using Azure OpenAI inside the server. It also distinguishes itself from siblings by noting it renders no card of its own and that it consumes search_buses output rather than making its own searches.

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 a clear call context ('used by the bus results card after it renders') and a preference rule ('prefers the search_context that search_buses returned, so no second search is needed'), plus the fallback condition ('re-fetches the route only when that handoff is missing'). It stops short of stating explicit exclusions or when not to call it.

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