hk_ipo_amount_payable

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

With no annotations, the description carries the full burden, and it does well: the explicit fee formula makes clear this is a deterministic, side-effect-free calculation with defined rounding ('each rounded to the cent'). It stops short of stating outright that it performs no transaction or that the result is not a guarantee of allotment, but the calculation nature is unambiguous.

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, both dense with useful content: the first defines the computation and its exact fee components, the second delivers the one-lot shortcut. Nothing is redundant and the core definition is front-loaded.

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 two-parameter pure calculator with no output schema, the description provides enough to call it correctly and to understand the composition of the result. It does not explicitly say the return value is a single monetary amount, which is the only remaining ambiguity.

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%, so the description must compensate, and it does: offer_price is identified as HK$ currency and shares as a share count, plus the practical alias that board lot size yields the entry fee. The rounding convention is also conveyed. Minor gap: no stated type/range expectations for offer_price beyond currency units.

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 names the exact computed quantity (amount payable to apply for HK IPO shares) and enumerates the components that make it up, so there is no ambiguity about what the tool returns conceptually. It is clearly distinct from siblings like hk_sell_costs or hk_ipo_plan, which cover different stages of 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?

It offers one concrete usage hint — pass shares = board lot to get the one-lot 'entry fee' — which is genuinely useful. However, it never states when to use this tool versus alternatives (e.g., hk_sell_costs for exit costs) or any preconditions, so routing still requires inference from the name.

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