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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on non-obvious behavior they don't cover: sign-in/API-key requirement, quota consumption per row, the today default, and the shared query_table response envelope. That is meaningful context an agent needs before calling.

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?

Three dense sentences, front-loaded with the core capability and default, followed by the NFL exclusion and then operational constraints. Every clause carries information; nothing is redundant with the schema.

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 still tells the agent the return shape by pointing to the query_table games envelope, and it covers defaults, league scope, auth, and quota. Nothing needed to invoke it correctly 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 only 50% (league has no description), but the description compensates by enumerating the valid leagues and clarifying that date is a single US-Eastern calendar day defaulting to today. It doesn't restate the required status of league or the YYYY-MM-DD format beyond the schema, so it adds good but not exhaustive meaning.

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 precise verb+resource+scope: games scheduled or played on one calendar date, US-Eastern, limited to nba/mlb/nhl, defaulting to today. It also explicitly separates itself from the query_table path used for NFL, so an agent can distinguish it from siblings without reading any schema.

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 names a concrete alternative and the condition that selects it: 'NFL is week-based ... for nfl, use query_table on nfl/games with season_id + week filters instead.' It also surfaces the auth prerequisite. It does not explain when to prefer this tool over query_table for the three supported leagues, so it stops short of full routing guidance.

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