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

Annotations already state that this is a read-only, idempotent, closed-world tool. The description still adds real context: it says there is no lookahead, that the result is the most recent published date not later than as_of_date, and that each call is billed. This last point about fallback behavior is not obvious and is not in the schema; it is behavior an agent would otherwise have to guess.

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 compact and front-loaded: the purpose and PIT definition come first, then the result semantics, then billing. It repeats the title string at the start, which is mild redundancy, but nothing else is wasted.

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 five-parameter read tool with no output schema, the description covers purpose, as-of-date fallback behavior, and cost. It could say more about the shape of the returned records, such as the fields of a score entry, but an agent has enough to invoke it correctly.

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 coverage is 100%, so the parameters are already documented. The description adds the non-obvious fallback semantics of as_of_date ('returns data for the most recent published date not later than as_of_date'), which goes beyond the schema's 'snapshot date' label. The other parameters (limit, offset, min_score, agency_id) get no extra meaning beyond their schema descriptions.

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 uses a concrete verb and resource: it looks up a point-in-time score for an anonymous agency/KOL on a given day. The parenthetical definition of PIT ('only uses data known that day, does not peek at the future') clearly distinguishes it from plain history or ranking siblings. It does not explicitly name get_agency_history or get_agency_ranking, so it falls short of a top score.

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?

'适合回测' gives a clear use case for when to prefer this tool. It also warns about cost ('每次调用计费 1 次'), which helps an agent decide whether to call it. It names no alternative sibling or exclusion condition, which keeps it at 4 rather than 5.

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