buy_taiwan_stock

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

With no annotations, the description fully discloses behavior: it is a simulated (模擬) operation, computes fees and tax, enforces the 1000-share lot rule, and defines the exact return structure including all fields. It also lists specific error scenarios, providing complete transparency about what can go wrong.

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 well-organized into purpose, examples, Args, Returns, and Raises sections. It is comprehensive without being bloated; every sentence adds value, and the critical lot-size rule is highlighted early and repeated in the args section for emphasis.

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 tool with no output schema and no annotations, the description is complete. It covers input semantics, return fields, error causes, and usage examples. An agent can invoke this tool correctly without needing additional external documentation.

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 schema has 0% description coverage, so the description must and does compensate. It explains symbol (股票代碼), quantity (must be multiples of 1000), and optional price (defaults to market price), reinforced by concrete examples. Every parameter's meaning and constraints are fully detailed.

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 clearly states the tool's purpose: '模擬台灣股票買入操作' (simulate Taiwan stock buy operation) and details that it executes simulated buy transactions while calculating fees and taxes. It distinguishes itself from sibling tools like sell_taiwan_stock by the buy action, and from get_* tools which are read-only.

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 provides clear context: it is for simulated buying, with examples showing how to use market and limit orders. It does not explicitly name alternatives or say when not to use it, but the buy vs. sell distinction is obvious from the tool name and sibling list, so the usage context is clear.

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