Get MaxPreps team rankings

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context beyond these: it mentions pagination (25 per page), the season behavior (current season may be empty for future sports), and that the tool is for discovery (returns teamPath for use in other tools). These are valuable details not captured by the annotations, so a 4 is appropriate.

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, three sentences, and front-loaded with the key purpose. It avoids fluff, and each sentence adds a distinct piece of value: what the tool returns, how it's used for discovery, and behavioral caveats. It's well-structured, making it easy for an agent to parse quickly.

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?

Given the tool's complexity (4 parameters, 1 required, no output schema), the description is quite complete. It covers pagination, season edge case, and the integration with other tools. The only minor gap is not explicitly stating that the output is purely for display purposes or that the teamPath can be used with specific sibling tools, but these are implied. The description provides sufficient context for an agent to call the tool correctly without ambiguity.

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 100% – every parameter (sport, state, season, pageNumber) has a description in the schema itself. The description reinforces the purpose of state (omit for national), season (omit for current), and pageNumber (25 per page), but doesn't add new semantic detail beyond what's in the schema. Baseline 3 is appropriate since the schema already handles parameter documentation adequately.

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 that this tool returns a ranked leaderboard of teams for a sport, either nationally or within a state. It specifies the exact resource (team rankings), the verb (get/list), and the scope (national or state). It also differentiates from siblings by noting it's the way to discover teams rather than look one up, and mentions the teamPath field that connects to other team 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?

The description provides clear context on when to use this tool (to discover teams) and mentions that omitting season gives the current season, which may be empty before the sport is underway. It doesn't explicitly name alternatives, but it contrasts with 'look one up' (implying search), and notes this is the discovery path. It could be improved by explicitly naming the sibling alternatives like maxpreps_search or maxpreps_list_teams, but the guidance is generally clear.

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