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

Annotations already include readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, but the description adds valuable behavioral context beyond these: it explains that the tool computes figures from nflverse data, returns the reason and nearest coverage when a figure cannot be served, carries execution details (method, population size, measure definition, data version), and defaults fantasy scoring to half-PPR while stating the used scoring in responses. This enriches the agent's understanding of what to expect from the tool.

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 moderately long but well-structured, starting with a clear directive ('Call this for any question about NFL statistics...'), then elaborating on computation logic and parameter roles. Each sentence adds meaningful information: the warning about memory-based figures, the computation process, and the scoring convention detail. It is not verbose or redundant; it earns its length by providing essential guidance for a complex tool.

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?

The description is comprehensive for a tool with no output schema and complex nested parameters. It covers what the tool does, how it works, what to expect in responses (executed method, population size, measure definition, data version), and edge cases (unservable figures return reason and nearest coverage). Given the lack of output schema, the description adequately prepares the agent for invocation and interpretation, though it could have been slightly more explicit about the exact structure of the 'operation' object in parameters.

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 explains the four required parameters as a population (position, qualifying threshold), a window (seasons, weeks, team span, coach tenure), a named measure, and an operation (leaders, rank, count, only-who, per-season streak, share of total). It also details the 'scoring' parameter (standard, half_ppr, ppr) and its default (half-PPR). While it does not explain every sub-field (e.g., 'k', 'direction'), the core semantics of each parameter are clarified, which is significant given the complex nested object schema.

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 states the tool computes NFL statistics on request, enumerating the types of questions it answers (leaders, rankings, splits, career/team spans) and explicitly declaring it the only surface that computes such figures. It distinguishes itself from sibling tools like query_stat_leaders and verify_claim by emphasizing computed (not verified) results, making its unique role clear.

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 explicitly instructs to use this tool for any NFL statistics question including when the answer is believed known, and warns against relying on memory. It provides concrete when-not guidance (e.g., figures from memory are unsourced) and differentiates from related tools by stating it computes rather than looks up, and that responses are labelled as computed, not verified. This effectively guides selection among siblings like verify_claim and query_stat_leaders.

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