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

Beyond the read-only, open-world, idempotent, non-destructive annotations, the description adds substantial behavioral context: the weekly data.gov.hk feed since 2024-12-30, that it returns every historical appearance rather than only the latest, the fields returned, the found:false semantics, and the structural absence of address/status data. This is a rich, non-obvious 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 appropriately front-loaded with the core lookup action, then logically expands into return semantics, found:false behavior, and data limitations. It is long, but most sentences earn their place; only the parenthetical Chinese phrase and Cyber Search Centre detail are slightly expendable.

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 no output schema, the description fully explains what the agent will receive: per-appearance English/Chinese names, company type, optional HKEX ticker, and the found:false case. It also explains the data coverage and why certain fields are unavailable. Nothing critical is missing for correct invocation and interpretation.

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 input schema already documents both parameters with examples at 100% coverage, so the baseline is 3. The description reinforces that brn must be exact but adds no new parameter-level detail, and does not mention the 'since' parameter at all.

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 states a specific verb ('Look up'), a precise resource ('a single Hong Kong company by its exact Business Registration (BR) number'), and the exact source feed. It clearly distinguishes itself from sibling search/name-change tools by emphasizing single-company exact BR lookup and describing the exact return contents.

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 conveys appropriate usage context: exact BR-number lookup against a specific feed, with clear interpretation of found:false (pre-dates feed or invalid BR). It also explicitly states what it does NOT return (registered address/status), which sets expectations, though it does not name sibling tools as alternatives.

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