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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine context by disclosing the upstream source (TWSE QFII register) and the existence of a statutory ceiling/headroom concept, but says nothing about data freshness, update cadence, or 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?

Front-loads the core value proposition and then branches into the two modes in a single dense sentence. It is information-rich without filler, though the long compound sentence is slightly heavier than necessary for a two-parameter tool.

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 only two optional parameters, no output schema, and annotations covering the safety profile, the description provides enough for an agent to select the right mode and call the tool correctly. Only the return-field layout and data currency are left implicit, which is a minor gap given there is no output schema to lean on.

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 both parameters (mode enum, limit range) are already documented in the schema. The description adds marginal value by explaining that top_holdings includes remaining headroom under the statutory ceiling, but offers no syntax or format detail beyond the schema, 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?

States a specific verb+resource (foreign/mainland-China ownership of the Taiwan stock market) and clearly enumerates the two output shapes: top holdings with remaining ceiling headroom, or ownership broken down by sector. It distinguishes itself from siblings like taiwan_stock_valuation or taiwan_market_summary by naming the TWSE QFII register and the ownership-specific framing.

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 two mode descriptions, plus the quoted example questions ("how much of TSMC do foreigners own", "foreign ownership of Taiwanese banks"), make the intended use cases clear. However, it never explicitly names a sibling or states when NOT to use this tool (e.g., versus taiwan_stock_quote for price data), so it stops short of full routing guidance.

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