article_oman_rv

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

Annotations already mark it as read-only, idempotent, and non-destructive, so the bar is lower. The description adds meaningful context: the data comprises daily non-parametric realized volatility measures, these are not forecasts, and the data is provided 'as is' for informational purposes. This goes beyond the annotations and helps set expectations about the data's nature.

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 bloated with boilerplate text copied from the Oxford-Man website, including background on research, disclaimers, and 'visually explored' commentary that is not relevant to tool invocation. The useful parameter lists and symbol table are embedded in this verbose prose, and the table is truncated, making it poorly structured for quick consumption.

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 two-parameter data-fetch tool, the description provides the symbol list, index list, and an availability table, which is helpful for understanding coverage. However, it lacks details on the returned DataFrame's structure (columns, date range) and is cut off mid-table, leaving the content incomplete. It does not clarify the difference from the sibling short version.

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%, so the description must compensate. It lists all valid values for both symbol and index, and provides a table mapping symbols to asset names and availability date ranges. This gives agents the ability to select valid parameters, though it does not explain what each index metric (e.g., medrv, rk_twoscale) represents.

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 indicates this tool provides data from the Oxford-Man Realized Library, with parameters for symbol and index, and returns a pandas.DataFrame. The verb is implicit ('数据' meaning 'data'), but it is evident that it retrieves realized volatility data for a given symbol and index. It does not distinguish itself from the sibling tool article_oman_rv_short.

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 explicit guidance is provided on when to use this tool versus alternatives such as article_oman_rv_short or article_rlab_rv. The table of availability dates gives coverage information but does not explain selection criteria or scenarios for choosing this tool.

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