Ferry Crossings In An Area

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so the description doesn't need to restate safety. It adds valuable provenance and quality caveats beyond the annotations — data comes from OSM, the operator site is 'checked by hand' and booking links exist only 'where confirmed', and timetable availability varies. It does not mention result caps or ordering, which is a minor gap.

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 resource and scope, then the bounding-box convention, then narrowing and use cases — a logical progression. The attribute list sentence is long but each item conveys what a caller can expect, though it could be trimmed slightly.

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?

With an output schema present, the description need not explain return values, and it still summarizes the fields available. For a read-only spatial search, what remains unstated is only result limits/density behavior in a large bbox, a small but real gap for an open-world query tool.

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 coverage is 100%, so the schema already documents bbox ordering, query matching, country_code, cars_only default, and locale. The description mostly repeats the bbox longitude-first convention with the same kind of geographic example already in the schema, adding only the hint that query targets ports or operators. Baseline 3 is appropriate.

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?

Names a specific verb and resource ('Ferry and river crossing lines in a bounding box from OpenStreetMap') and enumerates the returned attributes, so the agent knows exactly what it gets. It also distinguishes itself from the sibling get_ferry_schedule by positioning itself as the discovery step that supplies that tool's id.

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 concrete usage scenarios ('which ferries go to an island or across a sea, strait or river') and an explicit follow-on routing ('to get the id for get_ferry_schedule'). It also names narrowing strategies (query for port/operator, country_code), leaving little to inference.

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