Canal Nav

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

With no annotations provided, the description carries the full burden and discloses key behavioral facts: it returns matching locations with coordinates, covers marinas/moorings/water points/other waterside facilities, and is limited to waterway locations. It does not mention edge cases like no results or result limits, but for a simple lookup it provides sufficient transparency.

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 three sentences, with the primary purpose first, practical usage second, and a scope-limiting caveat third. Every sentence adds value and there is no repetition or filler.

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?

This is a simple one-parameter lookup tool with no output schema, so the description's mention of returning coordinates and facility types provides reasonable expectations. It also situates the tool within the larger workflow by referencing plan_route and plan_round_trip, making it complete for its low complexity.

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 schema already fully describes the single 'name' parameter with examples, and schema description coverage is 100%, so the description adds limited extra semantics. The description reinforces that the name is a place or facility name on the waterways, which is useful but not a major addition beyond the schema.

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 specific verb ('Look up') and a clear resource ('place name on the British inland waterway network'), and it states the return value ('matching locations with coordinates'). It also distinguishes itself from siblings by explicitly noting it is not a general geocoder, differentiating it from tools like search_directory.

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 gives concrete use cases: disambiguating a place before plan_route or plan_round_trip, and getting coordinates for a known spot. It also states a clear when-not ('not a general geocoder'), though it does not name an alternative tool for general geocoding, so it stops short of full alternative guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the data source freshness (refreshes from published notices), the nature of returned data (active and upcoming notices with dates, authority, navigation-blocking status, links), and implies this is a read-only operation. It doesn't mention error handling or pagination, but the covered traits are meaningful.

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, somewhat dense paragraph, but every sentence contributes: scope, search options, return contents, and data refresh policy. It could be improved with bullet points for scannability, but it remains concise and information-dense without fluff.

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 there is no output schema and no annotations, the description covers the essential context: what data is returned, how to search, and the freshness of the data. It doesn't fully cover edge cases like empty results or maximum radius behavior, but for a straightforward lookup tool, it is largely complete and well contextualized.

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?

While the schema already documents all three parameters (100% coverage), the description adds critical usage semantics by clarifying that place and waterway are mutually exclusive ('Give this or waterway'), explaining the coordinate format ('lat,lon'), and noting the optional radius with a default. This enriches the parameter understanding beyond the schema.

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 explicitly states the tool returns live closure, stoppage, and restriction notices for British waterways, lists specific authorities to emphasize broad coverage, and contrasts with a common assumption (not just CRT). It also names the search methods and return contents, making its purpose unmistakable and distinct from sibling tools like plan_route or find_place.

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 gives clear search instructions: by place (name or lat,lon) with optional radius, or by waterway name. It also highlights coverage across all navigation authorities, which helps when to prefer this over a more limited tool. However, it doesn't explicitly mention when not to use it or contrast with alternatives, so it falls short of a 5.

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

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

No annotations are provided, so the description carries full burden. It goes beyond a basic summary by disclosing output variety (rings, out-and-back, fewest-locks), detailed output attributes (distance, lock count, day-by-day plan, moorings), and safety/timing behaviors (lock-aware timing, closures flagged, fit warnings, tidal warnings). This is rich behavioral context.

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 four sentences, each contributing unique information. It is front-loaded with the core purpose, then details options, safety aspects, and input flexibility. No redundancy or fluff.

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 the tool's complexity (9 parameters, no output schema), the description provides thorough contextual completeness. It explains the key return values (options, distances, plans, warnings) and covers safety considerations. The only omission is error handling, but that is not essential for tool selection and invocation.

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 all 9 parameters are already described. The description adds value by explaining that boat dimensions trigger fit warnings and that lock-aware timing relates to lock_minutes, which enhances understanding of the parameters' purpose. Baseline 3 raised to 4 for this added context.

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 tool's purpose: planning return-to-start cruises on GB inland waterways, sized by days. It distinguishes itself from siblings by explicitly mentioning circular loops (rings), out-and-back, and fewest-locks alternatives, which are unique to round-trip planning. The verb 'plan' and resource 'round trips' are specific.

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 implicitly differentiates this tool from plan_route by focusing on round trips, indicating when to use it. However, it does not explicitly say 'use this instead of plan_route when you need a return-to-start trip' or provide exclusions. The context is clear but not explicit about alternatives.

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

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

With no annotations, the description carries the full burden and fully delivers. It discloses that routes follow water not roads, counts locks, estimates time, automatically routes around closures, compares waiting vs. detour, gives per-waterway fit warnings, includes tidal safety warnings, and returns candidates on ambiguous names. This is rich behavioral disclosure.

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 long but every sentence earns its place. It is front-loaded with the primary purpose, then systematically covers routing behavior, closures, boat limits, tidal warnings, and input formats. No fluff or repetition; the structure is logical and dense.

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 the tool's complexity (9 parameters, no output schema), the description is comprehensive. It explains core behavior, closure handling, detour comparison, fit warnings, tidal warnings, and input ambiguity. It doesn't explicitly describe the response format (e.g., list of waypoints, but it mentions 'returns the candidates' and 'the result compares waiting'), so a 4 is appropriate rather than a 5.

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 baseline is 3. The description adds value beyond schema by explaining why boat dimensions matter ('Give boat dimensions to get per-waterway fit warnings') and how place names or coordinates are interpreted, including the ambiguity behavior. These insights complement the schema's field-level descriptions.

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 opens with a clear, specific verb and resource: 'Plan a boat journey between two points on the inland waterways of Great Britain.' It distinguishes itself from siblings by focusing on journey planning, while siblings like 'find_place' or 'get_closures' serve different purposes. The scope (canals and navigable rivers) is 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?

The description provides clear context for when to use the tool (planning a boat journey, with lock counting, closures, boat-dimension checks, and tidal warnings). However, it doesn't explicitly mention alternatives or exclusions (e.g., when to use will_my_boat_fit instead), so it stops short of a 5. The guidance is implicit in the feature list.

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

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

With no annotations provided, the description carries the full burden. It adds useful behavioral context: the geographic scope (British inland waterways), the proximity radius is implied by the schema's 'approx. 15 km' note, and it discloses the unclaimed-listing claim feature with a URL. It doesn't describe result format or pagination, but for a straightforward search tool, this is reasonable.

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 three sentences, front-loads the core action, and uses a bullet-like list for categories. The list is long but informative. The final sentence about unclaimed listings is somewhat tangential but still relevant to what the results may contain. It is efficiently written without significant waste.

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 no output schema, the description reasonably sets expectations about what is searched and what types of results to expect (business listings with an unclaimed marker possibility). It covers the geographic scope, filtering options, and a special feature. It omits details like sorting or result count, but those are not essential for a search tool at this tier.

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 all parameters. The description mentions 'free text, category, or proximity to a place' which maps to query, category, and near, but adds no new detail beyond the schema's property descriptions. It earns the baseline 3, not higher.

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 begins with a specific verb and resource: 'Search Canal Nav's directory of waterside businesses on the British inland waterways.' It enumerates concrete business categories and clearly distinguishes itself from sibling tools (find_place, route planning, closures), which serve different purposes.

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 states the search scope and available filters ('Filter by free text, category, or proximity to a place'), giving clear context for when to use this tool. It does not explicitly name sibling alternatives or exclusion criteria, but the context is sufficient for an agent to know when search_directory is appropriate.

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

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

With no annotations, the description carries the full burden. It discloses that the answer is advisory and why, and states that it returns a per-dimension verdict quoting the limit. However, it does not describe behavior for partially provided dimensions or invalid waterway names, 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?

The description is three sentences: purpose+source, output behavior, and caveat+alternative. It is concise, front-loaded, and every sentence adds value without redundancy.

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?

The description covers what the tool does, what it returns (per-dimension verdict with limit), the advisory nature, and the alternative for journeys. No output schema exists, so the return description adequately covers that. For a simple query tool, the description is complete.

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 describes each parameter. The description adds context that the tool checks all four dimensions and that they are from CRT published figures, but it does not add additional semantics beyond the schema's parameter descriptions. Baseline 3 applies.

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 the specific verb 'Check' and clearly identifies the resource: 'boat dimensions against the published maximum craft dimensions for a named British waterway' (length, beam, draught and air draught). It further distinguishes itself from the sibling tools by explicitly recommending plan_route for whole journeys.

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 explicitly states when to use the tool (for a single named waterway) and when not to (for a whole journey, use plan_route instead). It also advises treating the answer as advisory due to varying draught and headroom, providing clear context.

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