Get Around Hong Kong

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds substantive context beyond that: the authoritative source (Immigration Department), the side of the border measured (Hong Kong side), direction (leaving and entering), and the resident/visitor split. It does not discuss refresh cadence or data staleness, which would matter for a 'right now' tool.

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 purpose and efficient given the breadth of coverage. However, it is one sprawling sentence and the full enumeration of eight crossing names is a keyword-stuffing dump that could have been trimmed or moved.

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-value explanation is not needed, and the description adequately frames the scope and data source. The main gap is the absence of any relationship to the plan_trip and service_updates siblings, which is the one thing an agent might still need.

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 100% and the single language parameter is fully documented with its enum values, so the schema does the heavy lifting. The description adds nothing about the language parameter, which is the correct baseline when the schema is complete.

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 specific resource (land and bridge crossings between Hong Kong and mainland China) and a specific measurement (current queue level and waiting range), enumerated by name across eight crossings. An agent can immediately tell this is a real-time status tool rather than a general travel planner.

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?

No explicit when-to-use guidance and no routing to alternatives. The closing phrase 'where to plan a trip to' gestures toward the plan_trip sibling but never names it or states the condition that would send the agent there, leaving the choice to inference.

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?

Annotations already declare read-only, open-world access. The description adds real context beyond that: the data source, exactly what each result contains (five-language titles, coordinates, nearest MTR, page link), and default date scoping. This is useful behavioral framing, not repetition.

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?

A single dense sentence that front-loads what the tool returns and follows with filter semantics. It never wastes words, though the parenthetical lists make it slightly run-on for scanning.

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 output schema and annotations already cover return shape and safety, and the description fills in source, fields, and default filtering. It's complete for invocation; the only miss is not guiding the agent toward siblings.

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 3 is a baseline. The description goes further by clarifying that 'from' defaults to today and that filtering is by events overlapping the from–to range with Hong Kong dates — meaning the schema's 'First day'/'Last day' labels don't fully convey.

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 specific resource (big events in Hong Kong) with concrete categories (concerts at major venues, sports, festivals, arts) and ties it to a recognizable source (getaroundhongkong.com/events). It doesn't explicitly distinguish itself from siblings like search_place, but the domain is clearly distinct.

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?

It implies when to use it (to find events) and explains the two filters (dates, featured) with defaults ('from today on by default'). However, it never names alternatives or says when another tool is the better choice.

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?

Beyond the readOnly/openWorld annotations, the description discloses real behavioral traits: results are live from operators, deduplicated to one entry per route+direction at its nearest stop, and each entry carries heading plus minutes to the next two departures. This tells the agent what the result set actually looks like, which the annotations do not.

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 core capability and ordering lead the description, and exclusions follow. The single long run-on sentence packing coverage, dedupe rule, and payload shape makes it denser than it needs to be, but nothing is wasted.

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 needn't detail return values, and it still summarizes them (heading, next two departures). Parameters are fully documented in schema, annotations cover safety/openness, and coverage/exclusion limits are stated, leaving no gap an agent needs to guess at.

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 100% and the `place` parameter already documents accepted forms (place name, address, "lat,lon") with examples. The description adds only the framing "No destination needed", which is useful but marginal; 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?

States a specific verb+resource ("What's leaving now from the MTR stations, bus stops and green minibus stops around a place") with an explicit scope and ordering rule ("nearest first"). It also carves out what it does not cover ("Trams, ferries and Light Rail aren't included"), which separates it from sibling tools without needing the schema.

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 explicit triggers ("for \"when's my bus\" or \"what leaves near here\"") and an explicit alternative with its condition ("for a trip from A to B use plan_trip"). It also states that no destination is needed, closing the most likely misuse path.

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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: results include live next departures, traffic delays, group fare totals, a map link, and -- importantly -- affiliate Klook ads mixed into the output, which is a disclosure an agent would otherwise not have.

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?

Two sentences, front-loaded with the core capability and then the result contents, with no filler. The trailing affiliate-ad note is short, honest and earns its place as a disclosure, though the dense comma-list style is slightly harder to scan than a structured breakdown would be.

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 annotations covering safety and a full output schema plus 100% schema coverage, the description's job is to frame scope and it does so well, including the ad disclosure. The one gap is routing guidance relative to search_place and service_updates, which would make it fully complete for a 13-parameter, multi-source 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 description coverage is 100% with 13 params, so the schema already documents place formats, party ages, enum values, arrive_by and step_free semantics. The description only alludes to these in passing ('Octopus fares for the group', 'best first') without adding syntax or edge-case guidance, so the baseline of 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 gives a specific verb and resource -- routing between two named points in Hong Kong -- and enumerates the modes covered (MTR, bus, minibus, tram, ferry) plus the output shape. It does not, however, reference the siblings search_place or service_updates to draw the boundary, so an agent must infer the split rather than being told it.

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?

Usage is implied by the shape of the tool (journey between two places), but there is no explicit when-to-use statement, no exclusions, and no pointer to service_updates for disruptions or search_place for resolving ambiguous place names. The agent is left to infer the routing rules.

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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; beyond that the description adds real behavior: results are ranked 'best first', the restaurant source is the official licence list, and passing `near` changes the ranking to nearest-branch-of-a-chain. With an output schema present it does not need to describe fields, and it does not.

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?

Two sentences, outcomes front-loaded ahead of the parameter tip, with essentially no filler. The first sentence is a dense list, but each enumerated place type adds genuine scope information rather than padding.

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, readOnly/openWorld annotations, and 100% parameter coverage, the description supplies everything an agent still needs: search domain, result ordering, ranking override via `near`, and data sources. No critical decision-relevant information is missing.

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 100%, so the schema already documents query, near and language (including the enum). The description's restatement of `near` ('rank a chain's branches nearest to a point') adds only a small amount of intent, not syntax or edge-case detail, so the baseline 3 is right.

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?

It names a concrete verb (matching text) and a rich, specific resource set — stations, stops, landmarks, restaurants, buildings and street addresses in Hong Kong — plus result ordering ('best first') and payload content (type and coordinates). The only gap is that it never references the sibling plan_trip to draw a boundary, so differentiation is inferred rather than stated.

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?

It explains the `near` condition for ranking a chain's branches by distance, which is genuine usage guidance. However, it never says when to prefer plan_trip over this tool, nor any exclusions (e.g. non-Hong Kong places, ambiguous queries), so the when-to-use-vs-alternative case is only implied.

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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond that: it names the data feeds (MTR next-train, Transport Department special traffic news), signals freshness ("right now"), and explains that empty lists mean nothing is reported — a non-obvious result semantic.

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?

Three short sentences, front-loaded with the core answer (what's disrupted now), then sources, then the empty-result rule and sibling relationship. No 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?

With an output schema present, return shapes need not be restated, and the description still covers the two data categories, their provenance, freshness, and empty-result meaning. Nothing an agent needs to call it correctly is missing.

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 single language parameter is fully documented in the schema (100% coverage) including its enum values and defaults, so the description adds nothing about it. Baseline 3 applies when the schema does the heavy lifting and the description is silent on parameters.

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 specific resource (live MTR delays and open road incidents) with its two upstream sources, and implicitly separates itself from plan_trip by noting that tool flags the same data on specific options. An agent can tell what this returns without opening the schema.

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?

"What's disrupted right now" plus "plan_trip also flags these on the options they affect" gives clear context for when to call it versus the trip-planning sibling, and the empty-list note tells the agent what a negative result means. It stops short of an explicit when-not rule, so 4 rather than 5.

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