stat-api — Sports Data

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious context beyond the annotations: the authentication requirement and the fact that each call consumes 1 record — a real side effect on the quota being reported.

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?

Two sentences, zero waste. The purpose and returned fields are front-loaded, followed by the auth and cost caveats. Every clause earns its place.

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 compensates by enumerating what the caller gets back (plan, limit, used, remaining, reset time). Auth requirements and the per-call cost are also disclosed, which is everything an agent needs for this trivial zero-param read.

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 by baseline this scores 4. There are no parameter semantics to document, and the description correctly spends its words on output content and prerequisites instead.

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 the exact resource ('your account's quota position') and enumerates the specific fields returned (plan, monthly limit, records used, remaining, reset timing). No sibling tool (describe_table, query_table, get_record, etc.) covers quota, so the differentiation is unambiguous.

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 states the precondition for calling it (a stat-api sign-in or API key) and the cost (1 record), which is useful operational context. However, it gives no explicit when-to-use or when-not-to-use guidance, which is only weakly implied by the tool's uniqueness among siblings.

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, but the description adds behavior they cannot express: no credentials are needed, the call is a prerequisite gate for query_table, and it emits a runnable example URL. It stops short of describing pagination or error behavior, but the safety and auth profile is well covered.

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?

A single dense paragraph with the payload description front-loaded and the critical usage rule in the final sentence, which lands where it will be read. Slightly overpacked with one list, but every clause carries information.

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 return-value disclosure itself and does so thoroughly: field types, filter syntax, page-size limits, primary key, and an example URL. Nothing an agent needs to call it correctly appears to be 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 description coverage is 0% and neither parameter is meaningfully explained. 'One table' loosely implies the table argument, but the league enum (nfl/nba/mlb/nhl/pga/dfs/reference) is never addressed, and the operators/filters described in the text belong to query_table, not to this tool's inputs — so the description does not compensate for the schema gap.

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 ('full contract for one table') and enumerates the concrete payload: fields with types, accepted filters with operators, page-size limits, primary key, and an example URL. It also names the sibling it pairs with (query_table), so an agent can place it in the workflow without opening either 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?

Explicit sequencing rule — 'Always call this before query_table' — plus a hard negative: 'filters not listed here are rejected.' That tells the agent both when to call it and what breaks if it skips the call, with no inference required.

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 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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered elsewhere. The description adds genuinely new behavioral context: authentication requirements and a quota cost, plus the return shape. It stops short of detailing error behavior for missing keys.

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 short sentences, front-loaded with the core action, then the return value, then the operational constraints. Nothing is wasted or repeated from 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 helpfully states that the row object is returned, and it covers auth and quota. The main remaining gap is the unspecified semantics of 'table' and 'league', though sibling tools (list_tables, list_leagues) can supply those values.

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 33% -- just 'id' is documented, while 'table' and 'league' (an enum of seven leagues) have no descriptions anywhere. The description mentions 'primary key' but adds no syntax, format, or guidance for selecting table/league, so the gaps are not compensated.

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 gives a specific verb and resource ('Fetch a single row by primary key') and states the return shape ('Returns the row object'). It distinguishes the tool implicitly from query_table/describe_table by emphasizing single-row primary-key lookup, but never names an alternative explicitly.

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 states prerequisites (stat-api sign-in or API key) and cost (1 record of quota), which is useful selection context. However, there is no explicit when-to-use-this-vs-siblings guidance, e.g. versus query_table or search_players, so usage is only implied by 'by primary key'.

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?

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.

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds real context beyond that: "No credentials needed" discloses the auth requirement, and it describes what is returned (table counts and availability).

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 short sentences, front-loaded with the resource, then the enumerated values, then the routing instruction. Every sentence carries information; nothing is padded.

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 compensates by describing the return content (leagues, table counts, availability) and the no-auth posture. For a zero-parameter discovery tool, an agent has everything needed to call it and to know what to do next.

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 nothing to disambiguate and the baseline is 4. The description correctly implies no input is required by noting no credentials are needed.

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 (List) and resource (every league/data group this API serves), and enumerates the concrete values returned (nfl, nba, mlb, nhl, pga, dfs, reference). It also distinguishes itself from the closest sibling by naming list_tables as the follow-up step.

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?

"Start here, then call list_tables" gives explicit sequencing and points to the next tool, so the agent knows the intended entry point and the alternative path. There is no explicit when-not-to-use clause, but for a zero-argument discovery endpoint the guidance is effectively complete.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds context annotations do not carry: that no credentials are required and that each row is a one-line summary, which sets expectations for the response.

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?

Two tight sentences; the purpose and scope are front-loaded and the sequencing hint follows without padding. Every clause earns its place.

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?

For a simple single-parameter read tool with full annotation coverage and no output schema, the description supplies purpose, auth expectation, response shape, and next-step guidance. 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 0% and the single 'league' enum has no per-value descriptions. The description does imply the call is scoped to exactly one league, which clarifies the parameter's semantics, but it adds nothing about the enum members or the required-ness.

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 (list), resource (queryable tables), and scope (one league) with the return shape ('one-line summary each'). This clearly separates it from list_leagues and the query tools in the sibling set.

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 the workflow ordering explicitly ('Follow with describe_table before querying') and notes 'No credentials needed', so the agent knows the natural next step. It does not, however, distinguish when to prefer this over list_leagues or query_table.

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), and the description adds material context beyond them: auth requirement (stat-api account or Authorization: Bearer key), quota cost per returned row, the exact response envelope, and pagination termination semantics. This is behavior an agent cannot infer from the annotations.

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 return shape and pagination walk come first, then filter syntax, then auth and quota. Every sentence is load-bearing, though the auth/quota sentence is tightly packed and the filter example could be a separate clause for readability.

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?

No output schema exists, so the description must describe returns itself, and it does precisely (table rows, limit, next_from_id, has_more). Auth, quota, pagination termination, and filter construction are all covered for a 5-parameter tool with nested-object filters.

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?

With only 40% schema coverage the description carries most of the burden and largely succeeds: it explains from_id as a keyset cursor with the 0-start convention, defines filters as a flat object of `field` or `field__op` keys, and shows a worked example including `day__between`. league and table values remain unexplained, though their enum and naming make them low-risk.

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 ('Query any table') and names the sibling table used to build filters (describe_table). It stops short of distinguishing itself from graphql_query, the other general query tool in the sibling list, so an agent still has to guess between the two.

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 concrete operational guidance: how to walk every row (from_id=0, follow next_from_id until null), what happens when from_id is omitted, and that filters keys come from describe_table. There is no explicit when-to-use/when-not rule relative to graphql_query or get_record, so it falls short of the top band.

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), but the description adds materially: authentication requirement ('stat-api sign-in or API key'), quota consumption, typo tolerance, and result ordering by match quality — none of which appear in structured fields.

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 tight sentences, front-loaded with the core purpose, then scope, alternative, and operational caveats. No filler or restatement of the title.

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 characterizes the return ('player rows ordered by match quality'). Combined with auth, quota, and league-limitation notes, an agent has everything needed to invoke this 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 description coverage is 0%, so the description must carry parameter meaning. It explains the 'name' parameter (fuzzy, typo-tolerant) and effectively explains why 'league' only accepts nba, but says nothing about 'limit' or its default/maximum beyond what the raw schema shows.

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 mechanism and resource: 'Fuzzy player-name search (typo-tolerant)' and clarifies scope with 'Currently NBA only'. It also distinguishes itself from query_table by naming that sibling as the route for non-NBA leagues.

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 routing: use this for typo-tolerant name lookup, and for other leagues use query_table with a name filter. This is an unambiguous when/when-not with the alternative named.

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