HK Transit Cost — MTR fares and the government fare subsidy

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

With no annotations, the description carries the full burden and does well: it discloses that this writes to the caller's own ledger, requires a bearer API key, and consumes the same monthly allowance as the REST endpoint (a quota constraint). It stops short of stating idempotency, duplicate handling, or failure behavior for a mutation 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?

Two sentences, front-loaded with the action and resource, then the side effects and auth/quota conditions. No filler; every clause carries information.

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 six-required-parameter mutation with no annotations and no output schema, the description covers auth, ledger target, and quota side effects well. It leaves open what the call returns (e.g., updated monthly total) and how duplicate or invalid trips are handled.

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 enums for mode and paid_with, so the schema documents all six parameters including examples for from/to. The description's parenthetical field list merely restates what the schema already provides, adding no new syntax or format detail.

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 and resource ('Record one public transport trip') and enumerates the payload fields it captures. The clause about counting toward a monthly total and subsidy estimate ties it to what the sibling read tools (monthly_summary, subsidy_amount) report, so the agent can place it in the workflow.

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?

Makes the write-vs-read split clear by describing this as the recording action that feeds the monthly total, implicitly contrasting with the sibling summary/fare tools. It does not explicitly say when NOT to use it (e.g., duplicate-trip handling) or name alternatives for correction/update scenarios.

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 behavioral burden and does disclose useful traits beyond the schema: an auth requirement ('Requires a bearer API key'), the read-only aggregation nature, and that the subsidy estimate is computed separately per Octopus and AlipayHK account. It stops short of stating read-only/destructive status explicitly or any rate limits.

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?

Effectively two sentences that are dense but front-loaded: the summary scope comes first, the auth requirement last. No filler, though the first sentence packs a lot of clauses together.

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 read-only single-parameter aggregation tool with no output schema, the description covers purpose, computed outputs, and auth needs. It is nearly self-sufficient; only explicit read-only/error behavior is left implicit.

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 month parameter is already documented as 'YYYY-MM' with a default. The description adds no format, syntax, or boundary detail beyond the schema, so the 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?

States a specific verb (Totals) and resource (one month of recorded trips) and enumerates exactly what is aggregated: trip count, total fare, mode/account breakdown, subsidy estimate. It does not explicitly differentiate itself from siblings like subsidy_amount, so it falls short of a 5.

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 ('Totals for one month from the trips you recorded'), but there is no explicit when-to-use or when-not guidance and no named alternative. Given the sibling subsidy_amount also touches subsidy computation, the lack of routing guidance leaves potential confusion.

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 does well: it discloses read-only access, no key required, determinism ('same input, same answer'), the fare categories returned, and that a source URL is included. It lacks rate-limit or failure-mode notes, keeping it short of a 5.

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 tight sentences, front-loaded with the core purpose and followed by return payload and operational traits. Every clause adds information; 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?

No output schema exists, so the description's enumeration of returned fare types (Octopus adult/student/JoyYou-sixty/child/elderly/PWD, single-journey adult, HKD, source URL) fills that gap. Combined with the no-key/read-only notes, an agent has everything needed to call it correctly.

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 both parameters are documented with examples in the schema; the description only restates that inputs may be a station name or MTR station id. Baseline 3 applies since the schema already carries the parameter detail.

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 ('look up') and resource ('published MTR fare between two stations in Hong Kong'), plus the input format. Clearly distinguishable from the sibling tools log_trip, monthly_summary and subsidy_amount, which do not retrieve published fare tables.

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 clear context: fare lookup between two named/id stations, deterministic, no key. It does not name an alternative tool or state when-not to use it, but the siblings are functionally distinct enough that this is a minor gap.

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 does so: it discloses the exact statutory formula, the $500 threshold and $400 per-account cap, that the two accounts are never combined, that the operation is deterministic arithmetic, read-only, and requires no key. Return values are also described, so nothing material about behavior is left implicit.

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 purpose, then the rule, then the return format and safety profile. It is slightly long but every sentence carries distinct information (formula, account independence, output figures, determinism).

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?

There is no output schema, yet the description states what is returned (truncated whole-dollar figure and exact one-third figure), and it supplies the full rule and constraint set. For a deterministic two-parameter computation tool, an agent has everything needed to call it correctly.

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 goes beyond the schema by clarifying the crucial parameter interaction – the Octopus and AlipayHK amounts are evaluated separately and never summed – which materially affects how the caller should supply them.

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 ('Compute the Hong Kong Public Transport Fare Subsidy Scheme amount') scoped to one month and to two named accounts. This is clearly distinguishable from the sibling tools log_trip, monthly_summary, and mtr_fare.

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 makes the input context explicit ('from the expenses recorded under an Octopus account and an AlipayHK account' this month), which tells the agent when this tool applies. It does not name siblings or state when-not-to-use (e.g., versus monthly_summary), so it stops 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.