stat-api — Sports Data

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that an API key is required and that calling the tool costs 1 record, which are key non-obvious traits. It does not discuss errors or edge cases, but for a simple quota lookup this is adequate.

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 a single, front-loaded sentence that leads with the core purpose ('Your key's quota position') followed by a succinct list of output fields and key constraints. Every element earns its place with no redundancy or fluff.

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 simplicity (no parameters, no output schema), the description is fully complete. It covers what the tool returns, what it requires, and what it costs. An agent has enough information to select and invoke the tool 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?

The tool has zero parameters and an empty input schema. Per calibration, the baseline for zero parameters is 4. The description adds no parameter-specific details because none are needed; it correctly focuses on the outputs and prerequisites.

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 identifies what the tool does: it reports the API key's quota position, including plan, monthly record limit, records used, remaining, and reset time. This is a distinct resource and purpose compared to sibling tools, which focus on data queries and table operations.

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 gives clear context for when to use this tool: to check quota position before or during API usage. It states the prerequisite (requires an API key) and the cost (1 record), but does not explicitly mention alternatives or when not to use it. The use case is nonetheless unambiguous.

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?

With no annotations, the description carries the full burden and excels: it details what the response contains (fields, filters, page-size limits, primary key, example URL), states that unlisted filters are rejected, and clarifies authentication requirements. This is richer than a simple read-only hint.

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 with front-loaded core info; the first sentence enumerates the contract elements, and the second provides actionable constraints. No filler or redundancy.

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?

Despite lacking an output schema, the description enumerates return contents (fields, filters, limits, primary key, example URL) and adds usage constraints, making the tool fully understandable for a 2-parameter metadata lookup.

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 schema has 0% description coverage, so the description must compensate. It clarifies the tool's purpose but does not explicitly define the 'table' parameter beyond 'one table' or specify how league relates to table selection. The league enum is self-documenting, but table string semantics are left to inference.

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 states the tool provides the 'Full contract for one table' with fields, filters, limits, primary key, and example URL. This clearly identifies it as a schema/metadata introspection tool, distinct from siblings like query_table and list_tables.

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 gives explicit instruction: 'Always call this before query_table' and warns that filters not listed are rejected. Also notes 'No credentials needed,' providing clear when-to-use context and setting expectations.

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?

With no annotations, the description carries the behavioral burden. It explicitly discloses the API key requirement and that all returned rows count against quota, which is valuable operational context. It does not explicitly state read-only behavior or error handling, but the nature of the tool (fetching data) implies no side effects.

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 three sentences, front-loaded with the core purpose, followed by parameter clarification and return structure, then the API key/quota caveat. Every sentence contributes meaningful information without redundancy.

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 no output schema, the description provides a clear return shape (`{"kalshi": {events, markets}, "polymarket": {events, markets}}`) and explains the optional source behavior. It also covers auth (API key) and quota, making it complete for a tool of this complexity, though the nested market structure could be more detailed.

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%, but the description adds meaning for game_id (explaining it's the game's id from the league's games table, with golf specifically tournament id) and for source (implied via return shape 'only the requested sources'). League's enum values are self-explanatory, so the description compensates for the sparse 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?

The description clearly states the tool fetches prediction-market contracts (Kalshi/Polymarket) attached to a single sporting event, with specific resources (events, markets). This verb+resource combination distinguishes it from sibling tools like games_on_date or query_table, which serve different purposes.

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 implies when to use this tool (for prediction-market data on a specific game) and clarifies that game_id is the game's id from the league's games table, with golf's tournament id. However, it doesn't explicitly mention alternative tools or exclusions, so guidance is clear but not exhaustive.

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?

With no annotations, the description carries the full burden and does well: it discloses timezone handling, default-to-today behavior, response envelope reference (same as query_table), API key requirement, and quota consumption. It doesn't explicitly label the operation as read-only, but 'scheduled/played' and quota context imply a read operation.

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 sentences, front-loaded with the primary purpose, followed by return format, then the key exclusion/alternative, and finally operational constraints. Every sentence adds necessary information without fluff.

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?

The description covers all essential context for correct use: league scope, date semantics, timezone, default, NFL alternative, API key, and quota. Although there is no output schema, referencing the query_table envelope gives a clear pointer to the return format. No significant gaps remain.

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 covers date with pattern and default, but description adds US-Eastern timezone meaning and clarifies the league enum names explicitly ('nba, mlb, or nhl'). This adds value beyond the schema, especially for league which lacks a description 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?

The description clearly states the tool returns games for a specific calendar date across three leagues (nba, mlb, nhl) with a default to today. It distinguishes itself from siblings by explicitly noting the NFL exception and pointing to query_table as the alternative.

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?

Provides explicit when-to-use context (date-based leagues) and when-not-to-use (NFL is week-based, use query_table instead). Also mentions default behavior, timezone, API key requirement, and quota impact, giving clear operational 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?

No annotations are provided, so the description carries the full burden. It discloses that an API key is required and that the operation costs 1 record of quota, which is meaningful operational context beyond the 'fetch' action. It implies a read-only operation but does not discuss error behavior or not-found handling.

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 three concise sentences, each adding distinct information: the operation, the return type, and the usage cost. It is front-loaded and contains no filler or redundancy.

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 read tool, the description covers the essential context: purpose, return type, authentication, and quota cost. There is no output schema, so the return type description is helpful. However, it lacks explicit guidance on when to prefer this over query_table and does not mention behavior when the record is missing, leaving minor gaps.

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 only 33% (only 'id' has a description). The description adds no meaningful detail about 'league' or 'table'; it only reinforces that id is the primary key. It does not compensate for the missing parameter explanations, leaving users to infer league/table semantics from names/enums.

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 states 'Fetch a single row by primary key' with a specific verb and resource, clearly distinguishing it from sibling tools like query_table by emphasizing single-row/primary-key operation. It also specifies the return type ('Returns the row object').

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 for when to use the tool (when you need a single row by primary key), but it does not explicitly mention alternatives or exclusions relative to sibling tools such as query_table. The phrase 'single row by primary key' implies the appropriate scenario.

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?

With no annotations provided, the description carries the full burden and does so excellently. It discloses API key requirements, per-row quota accounting, pagination semantics, and warns about the schema size. This goes well beyond minimal safety details.

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 concise yet packed with essential information: purpose, query structure, a critical warning, and authentication/quota details. Every sentence earns its place with no redundancy.

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 complex GraphQL tool with no output schema, the description covers all critical operational aspects: what it does, how to structure queries, where to find the schema, what not to do, and quota implications. The optional output shape is inherently defined by the query itself, so no further explanation is needed.

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 must compensate. It provides meaningful context for the query parameter (root fields, filters, pagination) but does not explain the variables parameter at all. Partial compensation, but a gap remains.

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 it runs a GraphQL query to fetch relational data in one call, specifying the verb, resource, and unique value proposition (nested relations). It differentiates itself from siblings like query_table by emphasizing GraphQL and relational nesting.

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?

Explicitly tells users when not to use it (introspection queries) and directs them to use describe_table instead, providing a clear alternative. It also implies the ideal use case: needing relational data in a single call vs REST.

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?

With no annotations, the description carries the full burden. It discloses that no credentials are needed and that the response includes table counts and availability. It does not discuss error behavior or rate limits, but for a simple listing tool these are not critical. This goes beyond a minimal description.

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 two sentences with no fluff. It front-loads the action, provides concrete examples, states access requirements, and gives a clear next step. Every sentence 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?

Given the low complexity (no parameters, no output schema), the description fully covers what an agent needs: what the tool does, what info is returned, authentication, and how to proceed. This is complete for its scope.

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 has zero parameters, and the schema trivially covers 100% of them. The description adds no parameter details because none exist. Per the rubric, a baseline of 4 is appropriate when there are no parameters.

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 the tool lists every league/data group served by the API, naming specific examples (nfl, nba, etc.), and mentions table counts and availability. This is a specific verb+resource that distinguishes it from siblings like list_tables.

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 tells the agent to 'Start here, then call list_tables,' which provides clear sequential guidance. It also notes that no credentials are needed, implying it is a lightweight entry point. It could explicitly mention when not to use it or name alternatives, but the context is sufficient.

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?

With no annotations, the description carries the transparency burden. It discloses auth requirements (no credentials) and output format (one-line summaries), adding value beyond the tool name. It does not mention error handling or rate limits, but for a simple read-only list, this is adequate.

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, front-loaded with the core purpose, followed by essential usage notes. No filler or repetition.

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 one-parameter list tool, the description covers purpose, auth, output summary, and a recommended next step. It does not detail return structure, but the output is summarized as one-liners, which is sufficient for a tool of this simplicity.

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 description implies the league parameter ('in one league') but does not describe its values or behavior. Schema coverage is 0%, so the description partially compensates, but the schema already fully defines the league enum and requirement.

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 the tool lists every queryable table in a league with one-line summaries. It explicitly names the resource (tables) and scope (per league), distinguishing it from sibling list_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?

It provides actionable guidance: 'No credentials needed' and 'Follow with describe_table before querying.' However, it does not explicitly compare to alternatives like query_table or list_leagues, though the workflow is implied.

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?

With no annotations, the description fully discloses return format, pagination behavior, filter structure, API key requirement, and monthly quota impact. This is comprehensive behavioral transparency for a query tool.

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 dense but compact, with every sentence contributing critical information: return format, pagination, filters, auth, and quota. It is front-loaded and well-structured.

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?

Despite no output schema, the description covers return format, pagination, filter syntax, authentication, and quota—making it complete for a general-purpose query tool. It appropriately references describe_table for filter operators without overloading.

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 40%, but the description compensates by explaining the `filters` object format with an example, the `from_id` pagination cursor, and the `limit` field in the return. It adds meaning beyond the schema for the least obvious parameters.

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 starts with 'Query any table,' a specific verb+resource that clearly states the tool's function. It distinguishes itself from siblings like describe_table (schema), get_record (single record), and graphql_query (alternative query mechanism).

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 clearly implies this is the general-purpose table query tool and references describe_table for filter syntax. It lacks explicit when-not-to-use or named alternatives, but the pagination and filter context make the usage clear.

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?

No annotations are provided, so the description carries the full burden. It discloses typo tolerance, NBA-only scope, ordering by match quality, API key requirement, and quota accounting. This is substantial behavioral context, though it stops short of detailing pagination or error behavior.

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, each focused and informative. The opening phrase is immediately descriptive, and the rest adds necessary caveats without redundancy.

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 simplicity and lack of output schema/annotations, the description covers purpose, scope, ordering, and quota. It does not specify exact row fields or error scenarios, but these are not critical for an agent's basic invocation decision.

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 must compensate. It clarifies the 'name' parameter via 'Fuzzy player-name search' and the 'league' parameter via 'NBA only', but it does not explain the 'limit' parameter or its effect on quota and result count. Partial compensation leaves a 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?

The description 'Fuzzy player-name search (typo-tolerant)' uses a specific verb and resource and immediately conveys the core function. It also distinguishes from sibling tools by explicitly stating 'for other leagues query the players table with a name filter via 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?

It explicitly states when to use the tool ('Currently NBA only') and provides a concrete alternative ('for other leagues query the players table with a name filter via query_table'). This gives clear guidance on both usage and exclusions.

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