Lumify Sports Intelligence provides comprehensive sports data and AI-driven betting insights across major leagues (NFL, NBA, MLB, NHL, NCAAF, NCAAB, tennis, soccer, and more).
Sports & Seasons
List sports & leagues — Browse all supported sports, their leagues, and current season info
List seasons — Explore historical and current seasons per sport/league
Events & Scores
List events — Browse scheduled, live, and completed events filtered by sport, league, status, date range, team, or season
Search events — Query events using natural language (e.g. "live NFL games today", "college basketball this week")
Get event — Retrieve full details for a single event including participants, venue, scores, odds, and AI intelligence
Batch fetch events — Get details for up to 25 events in one call
Live scores — Get lightweight live score snapshots (status, period, clock, per-period scores)
Odds & Betting Data
Get odds — Retrieve current betting odds from a specific bookmaker or all books
Odds history — View historical line movement snapshots for an event
Betting splits — Get public betting splits showing bets% and handle% per bookmaker
AI Bet Intelligence
Get intelligence — AI-generated confidence scores, signal breakdowns, rationale, recommended bets with tiers, narratives, and analyst takes
Teams & Players
List/search teams — Browse teams filtered by sport, league, conference, division, country, or name
Get team — Full team profile including home venue
Search players — Find players by name, sport, country, ranking, or active status
Get player — Detailed player profile including stats, position, and rankings
Player events — View a player's schedule and results with date/status filtering
Provides access to real-time schedules, live scores, odds, line movement, public betting splits, and AI-powered confidence for FIFA World Cup and other soccer leagues.
Provides access to real-time schedules, live scores, odds, line movement, public betting splits, and AI-powered confidence for MLB games.
Provides access to real-time schedules, live scores, odds, line movement, public betting splits, and AI-powered confidence for NBA games.
Provides access to real-time schedules, live scores, odds, line movement, public betting splits, and AI-powered confidence for NHL games.
Official client libraries and Model Context Protocol (MCP) integration for Lumify, the agent-ready sports-intelligence API: real-time schedules, live scores, odds, line movement, public betting splits, and explainable AI bet confidence across MLB, NFL, NCAAF, NCAAB, NBA, NHL, tennis, and soccer (MLS, EPL, La Liga, Serie A, Bundesliga, Ligue 1, and UEFA Champions League).
This repository is the public home for the client SDKs, the MCP stdio bridge, and developer docs/examples. Lumify itself is a hosted API at
https://lumify.ai— you don't run a server yourself.
Everything here authenticates with a Lumify API key (lmfy-...).
Fastest — no signup: grab a free instant trial key at https://lumify.ai/docs/ai (click "Get instant trial key"). No account, email, or credit card — 100 credits, 14-day expiry. Paste it and start calling.
Persistent account: create a key at https://lumify.ai/api-keys — free trial with 1,000 credits, no credit card required.
export LUMIFY_API_KEY="lmfy-xxxxxx.yyyyyyyy"Related MCP server: SportIntel MCP Server
Runtime | Package | Install | Docs |
TypeScript / JavaScript |
| ||
Python |
| ||
LangChain |
| ||
LlamaIndex |
| ||
CrewAI |
| ||
MCP stdio bridge |
|
import { Lumify } from "@lumifyai/sdk";
const client = new Lumify({ apiKey: process.env.LUMIFY_API_KEY! });
const { sports } = await client.sports.list();
const event = await client.events.get(12345, { includeOdds: true, includeIntelligence: true });
console.log(event.status, event.intelligence?.bets);import os
from lumify import Lumify
client = Lumify(api_key=os.environ["LUMIFY_API_KEY"])
sports = client.sports.list()
event = client.events.get(12345, include_odds=True, include_intelligence=True)
print(event["status"], event.get("intelligence"))curl https://lumify.ai/v1/events?sport=nfl&status=inprogress \
-H "Authorization: Bearer $LUMIFY_API_KEY"Lumify runs a hosted MCP server at https://lumify.ai/mcp (Streamable HTTP,
JSON mode, stateless). Point any MCP-compatible client at it.
Remote (Cursor, VS Code, Claude Desktop with remote support):
{
"mcpServers": {
"lumify": {
"url": "https://lumify.ai/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}Local stdio (clients without remote MCP support):
{
"mcpServers": {
"lumify": {
"command": "npx",
"args": ["-y", "@lumifyai/mcp"],
"env": { "LUMIFY_API_KEY": "YOUR_API_KEY" }
}
}
}See the MCP bridge README and the MCP guide for the full tool catalog.
Demo | Path | Tutorial |
Live sports scoreboard |
cd examples/scoreboard
npm install && cp .env.example .env # set LUMIFY_API_KEY
npm start # → http://localhost:3000API reference: https://lumify.ai/docs/reference
OpenAPI: https://lumify.ai/docs/openapi (schema: /openapi.json · ReDoc · Swagger UI)
Guides (incl. MCP): https://lumify.ai/docs/guides
Quick start: docs/getting-started/quick-start.md
Agent cookbook: docs/agent-cookbook.md
Postman collection: docs/lumify.postman_collection.json
Questions and bugs: open an issue
Contribution guidelines: CONTRIBUTING.md
MIT © 2026 Lumify AI
Get multiple events by id in one call — for agents that already have a list of ids and want full detail for each without one call per event. Max 25 ids. Returns full detail for every id that exists plus a not_found list for any that don't (never billed). Use get_event for a single id, or list_events / query_events to discover ids first.
| Name | Required | Description | Default |
|---|---|---|---|
| bookmaker | No | Bookmaker for inlined odds; defaults to pinnacle, 'all' for every book. | |
| event_ids | Yes | Event ids to fetch (max 25); duplicates are billed once. | |
| include_odds | No | Inline current odds on each event (+1 credit per event when odds are available). | |
| include_intelligence | No | Inline bet intelligence on each event (+1 credit per event when available). |
| Name | Required | Description |
|---|---|---|
| total | No | |
| events | No | Full event detail (same shape as get_event) for every found id. |
| not_found | No | Requested event_ids that don't exist. Never billed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: not_found items are never billed, duplicates are billed once, and credit costs for include_odds and include_intelligence. This significantly enhances transparency.
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, well-structured paragraph. It front-loads the primary purpose, follows with constraints, then redirects to alternatives. Every sentence is necessary with no fluff. Efficient and clear.
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 tool with 4 parameters and simple batch retrieval, the description covers everything needed: the use case, limitations (max 25), billing behavior, parameter side effects, and related tools. Output schema exists, so return values are not required. No 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 coverage is 100% with individual parameter descriptions. The description adds contextual meaning beyond schema: clarifies credit implications for include_odds and include_intelligence, and reiterates max 25 and duplicate handling. While schema already covers basics, the description adds practical usage nuance.
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 action ('Get multiple events by id in one call') and the resource ('events'). It distinguishes itself from sibling tools like get_event (single id) and list_events/query_events (discovery), providing a specific verb+resource with scope.
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 states when to use this tool ('for agents that already have a list of ids'), when not to ('Use get_event for a single id'), and how to discover ids ('list_events / query_events'). Also specifies the max of 25 ids and billing behavior for not_found items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single event with participants and venue. Optionally inline current odds and/or bet intelligence (+1 credit each, only charged when that data is actually available). Raises a not-found error if event_id doesn't exist. Use list_events / query_events to discover ids first, or batch_get_events to fetch several ids in one call.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event id, from list_events, query_events, or search results. | |
| bookmaker | No | Bookmaker for inlined odds; defaults to pinnacle, 'all' for every book. | |
| include_odds | No | Inline current odds (+1 credit when odds are available). | |
| include_intelligence | No | Inline bet intelligence (+1 credit when available). |
| Name | Required | Description |
|---|---|---|
| id | No | |
| name | No | |
| sport | No | |
| venue | No | |
| league | No | |
| status | No | |
| starts_at | No | |
| updated_at | No | |
| participants | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint. The description adds that it raises a not-found error for missing event_id and explains credit costs for optional inlining, providing useful behavioral context beyond 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?
Extremely concise: two sentences that cover purpose, error handling, alternatives, and parameter nuances without wasted words. Information is front-loaded.
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 the presence of an output schema, the description fully covers purpose, usage, error conditions, param details, and cost implications. 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 100%, so baseline is 3. The description adds value by specifying event_id source, bookmaker defaults, and credit implications for include_odds and include_intelligence, going beyond schema descriptions.
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 'Get a single event with participants and venue' and distinguishes from siblings by mentioning list_events/query_events for discovering IDs and batch_get_events for multiple IDs.
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 says to use list_events/query_events to discover IDs and batch_get_events for multiple IDs, providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current betting odds for an event: per-bookmaker lines and last-updated time. bookmaker defaults to pinnacle; use 'all' for every book (costs 1 credit per book returned). Returns available:false with no charge if odds aren't posted for this event yet. Use get_odds_history for line movement over time instead of the current line.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event id, from list_events, query_events, or search results. | |
| bookmaker | No | Bookmaker slug, e.g. pinnacle (default) or 'all' for every book. |
| Name | Required | Description |
|---|---|---|
| event_id | No | |
| available | No | |
| bookmakers | No | |
| last_updated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: returns available:false with no charge if odds not posted, and credit cost for 'all' books. No contradiction with 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?
Two succinct sentences, front-loaded with purpose, then parameter details, then alternative. No 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 output schema exists and annotations are rich, the description covers purpose, parameters, cost, and alternative, making it fully sufficient.
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 100%, baseline 3. Description adds value by specifying default bookmaker and credit cost for 'all', which is not in 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 states the specific verb 'Get', resource 'current betting odds', and scope 'per-bookmaker lines and last-updated time', distinguishing it from siblings like get_odds_history.
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 when to use (current odds) and when not to (use get_odds_history for line movement), explains bookmaker default and 'all' option with credit cost.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get line-movement history for an event: a list of past odds snapshots (movements), each with its own timestamp, up to limit entries. bookmaker defaults to pinnacle. Use get_odds instead if you only need the current line.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max line-movement entries to return. Default 50. | |
| event_id | Yes | Event id, from list_events, query_events, or search results. | |
| bookmaker | No | Bookmaker slug; defaults to pinnacle. |
| Name | Required | Description |
|---|---|---|
| total | No | |
| event_id | No | |
| movements | No | Odds snapshots over time; each entry carries its own timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it returns a list of past snapshots with timestamps, up to limit entries. No contradictions. Adds value by detailing return format.
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 concise sentences: first defines purpose and output, second provides alternative tool. No redundant words.
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 output schema present and rich annotations, description fully covers purpose, default behavior, and when to use alternative. Sufficient for correct tool selection.
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 all 3 parameters with 100% description coverage. Description mentions default bookmaker and limit behavior but adds little beyond schema definitions.
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?
Description clearly states it retrieves line-movement history (past odds snapshots with timestamps). Distinguishes from get_odds which is for current line only.
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 directs to use get_odds for current line, specifies default bookmaker (pinnacle) and limit (50), providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single player profile: name, sport, country, position/handedness, physical stats, current team, and tennis ranking if applicable. Raises a not-found error if player_id doesn't exist. Resolve ids via search_players.
| Name | Required | Description | Default |
|---|---|---|---|
| player_id | Yes | Player id, from search_players. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| slug | No | |
| sport | No | |
| position | No | |
| birthdate | No | |
| full_name | No | |
| height_cm | No | |
| is_active | No | |
| weight_kg | No | |
| handedness | No | |
| country_code | No | |
| tennis_ranking | No | |
| current_team_id | No | |
| current_team_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds error behavior (not-found) and data fields included. Adds value beyond annotations without contradiction.
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, no fluff. Purpose front-loaded, key details included. Every word 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?
Output schema exists, so return values need not be detailed. Description covers error handling, data scope, and parameter origin. Complete for a simple lookup tool.
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 100% with a single parameter described. Description adds context: 'from search_players', which helps agent source the ID. Slight extra value over schema alone.
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?
Clear verb-resource pairing 'Get a single player profile' with explicit list of fields. Distinguished from sibling tools by focusing on player profile retrieval. Also mentions ID resolution via search_players.
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 states when to use (get a single player profile) and error case (not-found). Tells to resolve IDs via search_players. Could be stronger by stating when not to use (e.g., use search_players for lists), but adequate given context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a player's events (schedule/results), paginated by id (after_id). Defaults to ±30 days around today when no date filter is given. Resolve player_id via search_players first.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date YYYY-MM-DD. | |
| from | No | Start date YYYY-MM-DD. | |
| limit | No | Max events to return per page. | |
| status | No | Filter to events in this status. | |
| after_id | No | Cursor: last event id from the previous page's next_after_id. | |
| player_id | Yes | Player id, from search_players. |
| Name | Required | Description |
|---|---|---|
| data | No | Events in the same shape as list_events' EventSummary. |
| has_more | No | |
| player_id | No | |
| next_after_id | No | Pass as after_id to fetch the next page; null on the last page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: default ±30 days range and pagination via after_id. Annotations already indicate safe read-only operation, so the description enriches understanding without contradiction.
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 concise sentences with zero waste: first states core purpose, second details default behavior, third gives prerequisite. Perfectly front-loaded.
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 essential behavior (list player events, pagination, default dates) and prerequisite. With output schema existing, return format is handled elsewhere. Could mention ordering or that status filter is optional, but not critical.
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 adds value beyond the 100% schema coverage by explaining default date range behavior and instructing to use search_players for player_id. This clarifies parameter usage beyond schema descriptions.
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 a player's events (schedule/results) with pagination. It distinguishes itself from siblings like list_events (global) and get_event (single) by specifying player-specific filtering.
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 advises resolving player_id via search_players first, which is a crucial prerequisite. It also mentions default date range behavior. However, it does not explicitly state when not to use this tool versus alternatives like query_events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get public betting splits (bets% and handle%) for an event: a consensus split plus a per-book breakdown, with a captured_at timestamp. Returns available:false with no charge if splits haven't been captured for this event yet.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event id, from list_events, query_events, or search results. |
| Name | Required | Description |
|---|---|---|
| books | No | Per-bookmaker splits breakdown. |
| event_id | No | |
| available | No | |
| consensus | No | Aggregate bets%/handle% across books. |
| captured_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the valuable context that the tool returns available:false with no charge if splits are not yet captured, which is beyond the annotation information. It also mentions the captured_at timestamp, though does not detail all edge cases.
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 extremely concise, consisting of two sentences that effectively front-load the main purpose and then provide a specific behavioral detail. Every sentence adds value 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 low complexity (single parameter with full schema coverage), the presence of an output schema, and the description summarizing key output components, the description is complete for an agent to understand the tool's purpose and usage. No additional context 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 100%, with the sole parameter event_id already described clearly in the schema as coming from list_events, query_events, or search results. The description does not add further semantic detail beyond what the schema provides, so a baseline score of 3 is appropriate.
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 retrieves public betting splits (bets% and handle%) for an event, including a consensus split and per-book breakdown with a timestamp. It also specifies the behavior when splits are unavailable. This is a specific verb+resource that distinguishes it from sibling tools like get_odds.
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 usage by stating what the tool retrieves, but does not explicitly state when to use this tool versus alternatives like get_odds or get_odds_history. It does mention the case when splits are not captured (available:false), which provides some context but no direct comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List seasons per sport/league, optionally filtered by sport or to the current season only. Returns each season's id, year, phase, start/end dates, and whether it is_current. Use list_sports for just each sport's current season.
| Name | Required | Description | Default |
|---|---|---|---|
| sport | No | Filter by sport slug, e.g. nhl, nba, soccer. | |
| current_only | No | Return only currently active seasons. |
| Name | Required | Description |
|---|---|---|
| total | No | |
| seasons | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by specifying the return fields (id, year, phase, start/end dates, is_current), which helps the agent understand the output. No contradictions with 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?
Two concise sentences with no wasted words. The most important information is front-loaded: the action and resource, then optionality, then return details, then sibling reference.
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 an output schema present and the description covering the return fields, the description is complete. It also addresses the alternative tool, making it self-contained for an agent's decision-making.
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 input schema has 100% description coverage for both parameters (sport, current_only). The description adds context about optional filtering but does not provide additional meaning beyond the schema. Baseline 3 is appropriate.
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 'List seasons per sport/league' using a specific verb and resource. It also mentions optional filtering and distinguishes from the sibling tool 'list_sports' by noting that list_sports returns only the current season per sport.
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 this tool (listing seasons with optional filters) and explicitly names an alternative tool (list_sports). However, it does not explicitly state when not to use this tool, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List teams, paginated by id (after_id). Filter by sport, league, conference, division, country, active status, or name (q, partial match). Returns each team's id, slug, name, city, conference/division, and venue. Use get_team for full detail on one id once resolved here.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Team name search (partial match). | |
| limit | No | Max teams to return per page. | |
| sport | No | Sport slug, e.g. nfl, nba, soccer. | |
| active | No | Filter by active status. | |
| league | No | League slug, e.g. nfl, mls. | |
| country | No | ISO country code, e.g. USA. | |
| after_id | No | Cursor: last team id from the previous page's next_after_id. | |
| division | No | Division name, e.g. AFC East. | |
| conference | No | Conference name, e.g. AFC, Eastern. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| has_more | No | |
| next_after_id | No | Pass as after_id to fetch the next page; null on the last page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds value by mentioning pagination via 'after_id' and listing the return fields. While no contradictions, it doesn't add extensive behavioral context beyond what annotations provide.
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, and every sentence adds value. No unnecessary words. Highly efficient.
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 9 parameters, presence of an output schema, and comprehensive annotations, the description adequately covers pagination, filtering, and links to the sibling tool for more detail. It is complete for an agent to understand how to use this tool.
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 100% with descriptions for all 9 parameters. The description adds context by highlighting pagination mechanism ('by id (after_id)') and partial matching for 'q', and listing return fields. This provides meaningful additional information beyond the schema alone.
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 'List teams' and specifies pagination and filtering options. It distinguishes itself from the sibling 'get_team' tool by directing users to use get_team for full detail on a single team. This satisfies the high bar for purpose clarity.
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 explicit guidance: use this tool for listing teams with filters and pagination, and use get_team for detailed info on a specific team. It also implies usage through pagination via after_id. This clearly differentiates from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search events with a natural-language query instead of structured filters — e.g. 'live nfl games today' or 'college basketball this week'. Rule-based (not an LLM): recognizes sport (nfl/nba/mlb/nhl/tennis/soccer/ncaaf/ncaab + aliases like hockey, american football, college basketball), status (live/final/upcoming/…), dates (today/tomorrow, this week, next N days, YYYY-MM-DD ranges). Bare 'football' is ambiguous and left unrecognized. Response includes interpreted filters, equivalent REST call, and unrecognized_terms. Prefer list_events when you already know the structured filters you want.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Overrides any limit parsed from the query text. Max 100. | |
| query | Yes | Free text, e.g. 'live nfl games today'. |
| Name | Required | Description |
|---|---|---|
| query | No | The original natural-language query text. |
| total | No | |
| events | No | |
| interpreted | No | The list_events-equivalent filters parsed from the query text (sport, status, date, from, to, limit). |
| next_after_id | No | |
| equivalent_request | No | The literal GET /v1/events request this query was translated to. |
| unrecognized_terms | No | Query words that didn't map to a known filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Reveals rule-based (not LLM), lists recognized sports/status/dates, mentions ambiguity of 'football', and describes output fields beyond what annotations provide.
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?
Concise 3-4 sentences, front-loaded with purpose, no unnecessary words.
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 annotations, input/output schemas, and sibling context, description is complete: covers usage, limitations, and behavior.
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 100%; description adds value by explaining query as natural-language with examples and limit as override. Good but not exhaustive on format.
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 does natural-language event search, with examples like 'live nfl games today' and distinguishes from list_events.
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 says 'Prefer list_events when you already know the structured filters you want', guiding when to use this tool vs. the sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.2get_event6 fields changedOutput schema / properties / participants / items / properties / is_winner / typePrevious value: -"boolean"New value: +[
+ "boolean",
+ "null"
+]Output schema / properties / participants / items / properties / player / typePrevious value: -"object"New value: +[
+ "object",
+ "null"
+]Output schema / properties / participants / items / properties / score / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / participants / items / properties / team / typePrevious value: -"object"New value: +[
+ "object",
+ "null"
+]Output schema / properties / updated_at / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / venue / typePrevious value: -"object"New value: +[
+ "object",
+ "null"
+]get_intelligenceget_live_scoreget_odds1 field changedOutput schema / properties / last_updated / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_player9 fields changedOutput schema / properties / birthdate / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / country_code / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / current_team_id / typePrevious value: -"integer"New value: +[
+ "integer",
+ "null"
+]Output schema / properties / current_team_name / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / handedness / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / height_cm / typePrevious value: -"integer"New value: +[
+ "integer",
+ "null"
+]Output schema / properties / position / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / tennis_ranking / typePrevious value: -"integer"New value: +[
+ "integer",
+ "null"
+]Output schema / properties / weight_kg / typePrevious value: -"number"New value: +[
+ "number",
+ "null"
+]get_splitslist_eventslist_seasons5 fields changedOutput schema / properties / seasons / items / properties / end_date / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / seasons / items / properties / name / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / seasons / items / properties / phase / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / seasons / items / properties / start_date / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / seasons / items / properties / year / typePrevious value: -"integer"New value: +[
+ "integer",
+ "null"
+]list_teams9 fields changedOutput schema / $defs / Team / properties / abbreviation / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / city / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / conference / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / country_code / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / division / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / league / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / short_name / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / state / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / $defs / Team / properties / venue / typePrevious value: -"object"New value: +[
+ "object",
+ "null"
+]search_playersv1.0.1get_eventget_intelligenceget_live_scoreget_splitsget_teamlist_eventslist_seasonslist_teamsv1.0.0batch_get_eventsget_oddsget_odds_historyget_playerget_player_eventsget_splitsget_teamquery_eventssearch_playersEach tool has a clearly distinct purpose: batch_get_events for multiple event IDs, get_event for single event detail, get_live_score for lightweight scores, get_odds/get_odds_history for current/historical odds, get_intelligence for bet analysis, get_player/get_player_events for player info, list_events/list_teams/list_seasons for general listings, query_events for natural language search, and search_players for player search. No two tools have overlapping functionality.
All tool names follow a consistent verb_noun pattern in snake_case: get_*, list_*, search_*, query_*, batch_get_*. The verbs and nouns are descriptive and uniformly formatted.
With 13 tools, the set is well-scoped for a sports intelligence API covering events, teams, players, seasons, odds, and live scores. Each tool serves a distinct need without unnecessary redundancy.
The tool set has a significant gap: list_teams explicitly references a get_team tool for full team detail, but it is not present. This omission creates a dead end for agents that need to retrieve detailed team information after identifying team IDs. Additionally, there is no get_season tool, though list_seasons may suffice. The missing get_team tool undermines completeness for a read-oriented API.
Sports odds, player props and source coverage for AI assistants. Connect with your own API key.
Sports data across 8 sports under one canonical schema — scores, stats, standings, Elo, odds
NFL/NBA/MLB/NHL/PGA + DFS and prediction-market data. Browse free; query with a free API key.
Live odds, cross-book +EV and graded player-prop results across 27 books. Hosted endpoint included.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lumifyai/lumify'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
