movie_boxoffice_yearly

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful context by providing the source URL and clarifying that the date parameter selects the year containing that date. However, it does not disclose data freshness, potential delays, or edge-case behavior such as invalid dates or empty results.

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 short and structured as a docstring with param, type, return, and rtype sections. The URL is useful for provenance. The only minor redundancy is that the first line repeats the title/annotation, but overall the content is concise and free of 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 single-parameter read-only tool, the description provides the source URL, parameter semantics, and return type. However, there is no output schema and no description of the DataFrame's columns, index, or typical row count. It also lacks context about how this tool relates to the numerous movie box office siblings, which could leave an agent uncertain about which to select.

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 single parameter 'date' is described as '当前日期所在年度的票房数据' (box office data for the year containing the current date), which adds meaning beyond the raw schema by linking the date to a yearly aggregation. The default value '20240218' hints at the YYYYMMDD format, but the description does not explicitly state the expected format, range, or whether the date must be a trading day.

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 identifies the tool as '电影票房-年度票房' (movie box office - annual) and states that it returns '年度票房' (annual box office) as a DataFrame. This clearly indicates the annual scope and, through the name, helps distinguish it from sibling tools like movie_boxoffice_daily and movie_boxoffice_monthly. However, it lacks an explicit verb like 'fetch' or 'query' and largely repeats the title.

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 no guidance on when to use this tool versus alternatives. It does not mention that it is appropriate for annual box office data while daily, weekly, monthly, or real-time siblings exist for other time granularities. No exclusions, prerequisites, or alternative recommendations are given.

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