Fill My Bracket

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the scoring system (1-2-4-8-16-32, max 192), the year range with the 2020 exclusion, and the frame that this is counted history rather than a prediction with no betting advice. That framing is valuable, though the return-shape detail overlaps with completeness rather than behavior.

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 scope and year range are front-loaded, but the body is two very long sentences packed with parentheticals, and the 'counted history, not a prediction' idea is restated twice ('a recipe is what WOULD have scored'). Information-dense but not tight; some clauses could be trimmed without loss.

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 describing returns, and it does: champion and Final Four, best total score and its recipe, best first-weekend score, counts of recipes matching the real champion and full Final Four. For a five-parameter read-only tool, an agent has everything needed to call 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 baseline would be 3, but the description earns more: it explains that year scopes the tournament and that supplying any of chaos/tiebreak/champion_pick/loyalty switches the tool from summary mode to scoring one concrete recipe. That mode-switch semantics is meaning the schema alone does not convey.

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?

States a specific verb and resource: returns the winning recipes for a past men's tournament, backtested by running the five-question engine over the real field. This is clearly distinct from the siblings (get_cinderella_radar, get_rankings, get_upset_counts), which cover different analytical surfaces.

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?

Explicitly separates the two invocation modes: with no style inputs it returns the year summary (champion, Final Four, best score, best first-weekend score, counts), and with style inputs it scores that exact recipe. The condition selecting each mode is clear. It does not name sibling tools as alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered; the description adds real context beyond that by pinning the snapshot to Sunday, November 1, 2026, stating it mirrors the site's rankings page "exactly as published," and disclosing provenance for the historical record (counted first-round results from 1985-2025). It also sets expectations that the output is descriptive, not predictive. Minor gap: nothing about payload size or whether a missing snapshot is possible.

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?

It is front-loaded with the action and resource in the first clause, and the second sentence exists to constrain interpretation rather than to pad. The middle enumeration is a long, dense run-on with nested parentheticals (league, AP votes, model rank, why line, 1985-2025 records), which costs readability but every clause carries distinct content.

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?

With no input schema to document and no output schema provided, the description carries the full burden of describing the return payload, and it does so by listing the three result groups and the fields within them. What is missing is the response envelope — whether results come back as structured objects or rendered text — but the substantive content is fully covered for a zero-parameter read tool.

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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly adds no parameter talk, though it does specify the fixed date context, which is the closest thing to an implicit argument for this call.

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 Fill My Bracket's Cinderella radar") and enumerates the three content blocks: unranked teams rated above poll votes, the watch list, and vulnerable ranked teams. That is far more specific than a restatement of the title, but it never contrasts itself with the closest sibling, get_rankings, leaving ambiguity about whether the radar is a subset of that tool.

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 only implied: the description frames the data as "November signals from the preseason poll," which suggests it applies during the preseason window, and the caveat that these are not predictions hints at how to interpret rather than when to call. No alternative tool is named and no exclusion is stated, so an agent must infer the boundary with get_rankings and get_upset_counts.

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

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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's remaining job is scope disclosure, and it does that well: men's only, main bracket from the round of 64, no First Four games. It also clarifies that results are counted historical facts rather than projections, which is behavioral context the annotations cannot express.

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 core scope and the three call modes are front-loaded in the first two sentences, which is the right ordering. It is slightly over-stuffed at the end, where 'not odds, not win probabilities for any future game, and not betting advice' states the same exclusion three ways.

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?

With no output schema, the description carries the burden of describing returns, and it sketches them adequately (seed line stated as wins in 160 games, typical yearly upset counts, furthest round reached, plus a whole-table mode). What is missing is finer return-shape detail such as field names or how the all-seeds table is arranged, but the dataset boundaries and invocation modes are complete for a two-optional-parameter read tool.

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 baseline is 3, but the description adds real meaning the schema does not: omitting both arguments returns the whole table, and the arguments are alternative lenses on the same dataset rather than combinable filters. That clarifies the optionality semantics beyond the bare 'Optional' markers.

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 specific verb ('Answers upset questions') on a precisely bounded resource: men's tournament, counted game by game, 1985-2025, 40 tournaments, 2,520 games. It also lists the concrete question types (seed-line first-round win rate, typical yearly upset count, deepest run by seed), which separates it from the sibling tools get_backtest and get_cinderella_radar.

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?

It says exactly how to invoke: pass a matchup ('12 vs 5'), a seed, or no argument for the whole table, which covers all three call modes. It also rules out forecast use ('not odds, not win probabilities... not betting advice'), effectively routing prediction questions elsewhere, though it never names the sibling tools it is being distinguished from.

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