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

Beyond the readOnly/idempotent annotations, the description discloses auth requirements ('stat-api sign-in or API key'), a quota rule ('every row resolved anywhere in the tree counts against quota'), and an operational constraint (no introspection, huge schema). These are exactly the traits annotations cannot express and materially affect how an agent constructs a query.

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?

Four sentences, no filler: purpose first, then query construction, then the introspection prohibition with alternative, then auth/quota. Each sentence carries distinct operational information and the ordering front-loads what an agent needs before writing a query.

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 and only two parameters, the description covers the gaps that matter: how to build the query, how to paginate, what not to send, authentication, and cost accounting. Return shape is implicit in GraphQL and the sibling list covers discovery, so nothing essential is missing.

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 0%, so the description has to carry the load: it explains that `query` uses league root fields (nfl, nba, …), REST-equivalent filter arguments, and `first`/`after` pagination. That is strong compensation for the primary parameter, but the `variables` parameter is never addressed, leaving one of two params uncharacterized.

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+resource ('Run a GraphQL query against the same data') and immediately differentiates from siblings by contrasting REST filter arguments and naming describe_table. The relational-nesting capability ('nest from a game to its teams/players/odds in one call') tells an agent exactly what this tool is for versus query_table.

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?

Explicit when-to-use (relation nesting in one call), explicit when-not ('Do NOT send introspection queries') with a named alternative (describe_table) and an escape hatch (the SDL URL). This is the rare case where both the positive and negative routing are spelled out.

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