statistics_reads

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

The description adds behavioral detail beyond the readOnlyHint annotation: each snapshot is counted only once, and native Codex direct use is marked as not collected. These are exactly the interpretation-relevant caveats an agent needs. The annotation is consistent, so no contradiction exists.

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 counting rule comes first, followed immediately by the snapshot dedup and exclusion caveats. There is no filler or repetition; every clause adds information.

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 read-only tool with one optional parameter and an output schema present, the description covers the essential semantics: what is counted, the grouping key, the dedup rule, and the data availability limitation. The main remaining gap is the unspecified meaning of days, which keeps it from being fully self-contained.

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 only parameter, days, has 0% schema description coverage and is not mentioned in the description at all. The name 'days' plus default 7 weakly implies a time window, but the description does not explain what days controls, how it bounds the statistics, or its accepted range. The description fails to compensate for the low schema coverage.

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 names a specific verb and resource: it 统计 Manager 完整读取, grouped 按原始Skill, and gives an explicit counting rule and data exclusion (原生Codex直接使用列为未采集). This makes it clearly an aggregate read-statistics tool, distinct from raw read/list siblings like codex_read or content_read.

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?

Usage context is implied: it is for Manager complete-read stats, not for raw Codex direct-use data. But there is no explicit when-to-use/when-not-to-use guidance and no named alternative tool for the excluded data, so the agent must infer routing from scope rather than being told.

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