stock_query_order

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

Without annotations, the description discloses the cache-vs-server behavior via the force_query parameter and indicates the return type as a list of current orders. However, it does not explicitly state that this is a read-only operation or mention prerequisites, error conditions, or real-time guarantees.

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 concise and well-structured with Args and Returns sections. Every sentence provides necessary information, and there is no unnecessary 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?

For a simple query tool, the description covers the essentials: purpose, parameters, and return type. An output schema exists, so not explaining the return structure in detail is acceptable. It could add usage context or prerequisites, but overall it is fairly complete.

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?

With 0% schema description coverage, the description fully compensates by explaining account_id as "Account ID" and force_query as "True to force refresh from server, False to use cache". This adds meaningful meaning beyond the schema's types and defaults.

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 "Query stock orders" with a specific verb and resource, distinguishing it from sibling tools like stock_new_order or futopt_query_order. It makes the tool's scope explicit (stock orders, not futures/options).

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?

No guidance is given on when to use this tool versus alternatives such as stock_query_match or futopt_query_order. The description only states what it does without contextual hints on when it should be preferred.

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