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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses a real behavioral rule: thresholds are only shown when the reconstruction matches the official figure (forecast.shown), and otherwise the block is explained without fabricating a substitute. That is meaningful context the annotations cannot convey. It says nothing about latency, data freshness, or failure modes for players with fewer than 20 differentials, which keeps it short of a 5.

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?

Dense but front-loaded: the core capability, then the forecast.shown gating rule, then the scope limit, then the conditional parameter behaviors. Every clause carries information, though the single long first sentence packs three distinct facts and would read better split.

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 six all-optional parameters and no output schema, the description carries the return-value burden well: it names what comes back (20 differentials, the 8 counting, the one exiting the window, adjusted gross targets, target gross) and explains the tee_required branch. The reference to forecast.shown is unexplained as a field name, and the behavior for players lacking a full 20-round history is not addressed.

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 relationships the schema does not: course_id plus the tee yields indicative adjusted gross scores, target_index yields the gross score needed to reach that index, and tee_id/layout/tee_color only become relevant after a tee_required response. That interplay is genuine added meaning, though the individual field meanings are already in the 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?

States a specific verb and resource with unusual precision: handicap explained and projected using the WHS calculation performed in code, returning the last 20 differentials, the 8 that count, and which one leaves the window on the next round. This clearly separates it from a static handicap read, but it never names the obvious siblings (get_handicap, playing_handicap, plays_like), so the agent must infer the boundary itself.

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 explicit scope limits: scope=next_round estimates ONE upcoming round, never a sequence of tournaments or a permanent rule, and it forbids the agent from doing the math itself. It also prescribes the follow-up flow when tee_required is returned (ask for the tee with the offered options). The missing piece is an explicit comparison to get_handicap or playing_handicap for when the user just wants the current index.

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