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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the data snapshot date, the fact that every result is stamped with the as-of date, that unknown teams yield a plain not-found with nothing invented, and that no-argument calls surface poll-vs-model gaps. Return-shape details at the field level are not given, but that is largely the only remaining gap.

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 front-loaded with the core behavior and the mode split is structured well, but it is dense and repeats its snapshot date three times (October 19, 2026; November 1, 2026; 'as of Sunday, November 1, 2026') and adds a Selection Sunday aside that is only marginally relevant. Trimming the date repetition and the 2027 tournament disclaimer would make it noticeably tighter.

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?

There is no output schema, so the description carries the burden of explaining what comes back, and it does so for both modes including the not-found case. For a two-parameter read-only tool this is close to sufficient; only the exact result structure and the limit/default interaction are left unstated.

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 both parameters are already documented, and the baseline would be 3. The description earns above baseline by describing the outcome of each mode: a team lookup returns AP rank or votes, model rank, and any radar or vulnerable-favorite note, while omission returns the full Top 25 plus the model's top 10. It never mentions how 'limit' interacts with the stated 'full Top 25' default behavior, leaving one small ambiguity.

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 ('Returns the current college basketball rankings') and pins down the exact content: Preseason AP Top 25 with first-place votes, others receiving votes, and Bart Torvik T-Rank model ranks. It also states the source (fillmybracket.com/college-basketball-rankings) and the as-of date, so an agent knows precisely what dataset this is versus the tournament-field tools.

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 is clearly spelled out for the two call modes: omit the argument for the full Top 25 plus the model's top 10, or pass a team name for a per-team breakdown. It also sets a negative boundary ('this is current-season data, not the 2027 tournament field'), which helps exclude the wrong intent. It does not, however, contrast itself with the sibling tools get_cinderella_radar, get_upset_counts, or get_backtest, so routing between them is left partly to inference.

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