spot_quotations_sge

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, covering the safety/liveness profile. The description adds the data source (SGE, with graph URL) and that this is real-time data, but says nothing about refresh rate, data latency, or response shape beyond a pandas DataFrame.

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?

It is reasonably short, but the raw docstring formatting (URLs on their own lines, Sphinx-style :param/:type/:return markers) is not front-loaded prose. The long symbol list is justified content, yet the structure is more machine-generated than purpose-oriented.

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 single-parameter, read-only quote-fetch tool with annotations handling the safety profile and no output schema, the definition supplies source, symbol domain, and a helper for symbol discovery. The only gap is explaining the returned DataFrame's columns/timeframe, which is minor given the tool's simplicity.

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% and there is no enum in the schema, so the description carries the full burden. It does this well by enumerating all 17 valid symbol values and pointing to the helper function for the symbol table. Minor deduction because the parameter is not explicitly named as such in prose, only via the :param symbol: docstring block.

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 title/description names a specific verb-resource pair: real-time quotation data from the Shanghai Gold Exchange (SGE), with source URLs. It clearly differs from most siblings, though it does not explicitly contrast with the closely related spot_hist_sge (historical) tool it sits beside.

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 points to ak.spot_symbol_table_sge() for retrieving the symbol list, which is genuinely useful usage guidance. However, it gives no explicit when-to-use vs when-not context, e.g. no statement that spot_hist_sge should be used for historical rather than real-time data.

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