Skip to main content
Glama

Nba

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Search Players

search_players
Read-onlyIdempotent

"Find NBA player [name]" / "search NBA roster for [X]" / "is [player] in the NBA" — search NBA players by name on BallDontLie. Returns position, height, weight, college, country, draft info, and current team. NOTE: per-season averages (PPG/RPG/APG) and career stats are NOT in this response — those require BallDontLie's ALL-STAR tier ($9.99/mo at https://www.balldontlie.io/) via the /season_averages endpoint, which is not currently exposed by Pipeworx. Free-tier _apiKey works for this tool.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of results to return (default: 10, max: 100)
queryYesPlayer name or partial name to search for
_apiKeyYesBallDontLie API key

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query for player names
totalYesTotal count of matching players
playersYesList of matching players
returnedYesNumber of players returned in this response

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / examples
      Added value: +[
+  {
+    "_apiKey": "your-nba-api-key",
+    "query": "LeBron James"
+  },
+  {
+    "_apiKey": "your-nba-api-key",
+    "limit": 5,
+    "query": "Luka"
+  }
+]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "players": {
+      "description": "List of matching players",
+      "items": {
+        "properties": {
+          "college": {
+            "description": "College attended",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "country": {
+            "description": "Country of origin",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "draft_number": {
+            "description": "Draft pick number",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "draft_round": {
+            "description": "Draft round",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "draft_year": {
+            "description": "Year drafted",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "height": {
+            "description": "Player height",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Player ID",
+            "type": "number"
+          },
+          "jersey_number": {
+            "description": "Jersey number",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "name": {
+            "description": "Full name (first + last)",
+            "type": "string"
+          },
+          "position": {
+            "description": "Player position",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "team": {
+            "description": "Current team information",
+            "properties": {
+              "abbreviation": {
+                "description": "Team abbreviation",
+                "type": "string"
+              },
+              "city": {
+                "description": "Team city",
+                "type": "string"
+              },
+              "conference": {
+                "description": "Conference (East/West)",
+                "type": "string"
+              },
+              "division": {
+                "description": "Division name",
+                "type": "string"
+              },
+              "full_name": {
+                "description": "Full team name",
+                "type": "string"
+              },
+              "id": {
+                "description": "Team ID",
+                "type": "number"
+              },
+              "name": {
+                "description": "Team name",
+                "type": "string"
+              }
+            },
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "weight": {
+            "description": "Player weight",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "query": {
+      "description": "Search query for player names",
+      "type": "string"
+    },
+    "returned": {
+      "description": "Number of players returned in this response",
+      "type": "number"
+    },
+    "total": {
+      "description": "Total count of matching players",
+      "type": "number"
+    }
+  },
+  "required": [
+    "query",
+    "total",
+    "returned",
+    "players"
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changed
    • removedInput schema / examples
      Removed value: -[
-  {
-    "_apiKey": "your-nba-api-key",
-    "query": "LeBron James"
-  },
-  {
-    "_apiKey": "your-nba-api-key",
-    "limit": 5,
-    "query": "Luka"
-  }
-]
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "players": {
-      "description": "List of matching players",
-      "items": {
-        "properties": {
-          "college": {
-            "description": "College attended",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "country": {
-            "description": "Country of origin",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "draft_number": {
-            "description": "Draft pick number",
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "draft_round": {
-            "description": "Draft round",
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "draft_year": {
-            "description": "Year drafted",
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "height": {
-            "description": "Player height",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "id": {
-            "description": "Player ID",
-            "type": "number"
-          },
-          "jersey_number": {
-            "description": "Jersey number",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "name": {
-            "description": "Full name (first + last)",
-            "type": "string"
-          },
-          "position": {
-            "description": "Player position",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "team": {
-            "description": "Current team information",
-            "properties": {
-              "abbreviation": {
-                "description": "Team abbreviation",
-                "type": "string"
-              },
-              "city": {
-                "description": "Team city",
-                "type": "string"
-              },
-              "conference": {
-                "description": "Conference (East/West)",
-                "type": "string"
-              },
-              "division": {
-                "description": "Division name",
-                "type": "string"
-              },
-              "full_name": {
-                "description": "Full team name",
-                "type": "string"
-              },
-              "id": {
-                "description": "Team ID",
-                "type": "number"
-              },
-              "name": {
-                "description": "Team name",
-                "type": "string"
-              }
-            },
-            "type": [
-              "object",
-              "null"
-            ]
-          },
-          "weight": {
-            "description": "Player weight",
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "query": {
-      "description": "Search query for player names",
-      "type": "string"
-    },
-    "returned": {
-      "description": "Number of players returned in this response",
-      "type": "number"
-    },
-    "total": {
-      "description": "Total count of matching players",
-      "type": "number"
-    }
-  },
-  "required": [
-    "query",
-    "total",
-    "returned",
-    "players"
-  ],
-  "type": "object"
-}New value: +null
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "players": {
+      "description": "List of matching players",
+      "items": {
+        "properties": {
+          "college": {
+            "description": "College attended",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "country": {
+            "description": "Country of origin",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "draft_number": {
+            "description": "Draft pick number",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "draft_round": {
+            "description": "Draft round",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "draft_year": {
+            "description": "Year drafted",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "height": {
+            "description": "Player height",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Player ID",
+            "type": "number"
+          },
+          "jersey_number": {
+            "description": "Jersey number",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "name": {
+            "description": "Full name (first + last)",
+            "type": "string"
+          },
+          "position": {
+            "description": "Player position",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "team": {
+            "description": "Current team information",
+            "properties": {
+              "abbreviation": {
+                "description": "Team abbreviation",
+                "type": "string"
+              },
+              "city": {
+                "description": "Team city",
+                "type": "string"
+              },
+              "conference": {
+                "description": "Conference (East/West)",
+                "type": "string"
+              },
+              "division": {
+                "description": "Division name",
+                "type": "string"
+              },
+              "full_name": {
+                "description": "Full team name",
+                "type": "string"
+              },
+              "id": {
+                "description": "Team ID",
+                "type": "number"
+              },
+              "name": {
+                "description": "Team name",
+                "type": "string"
+              }
+            },
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "weight": {
+            "description": "Player weight",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "query": {
+      "description": "Search query for player names",
+      "type": "string"
+    },
+    "returned": {
+      "description": "Number of players returned in this response",
+      "type": "number"
+    },
+    "total": {
+      "description": "Total count of matching players",
+      "type": "number"
+    }
+  },
+  "required": [
+    "query",
+    "total",
+    "returned",
+    "players"
+  ],
+  "type": "object"
+}
  4. Changed1 schema field changed
    • addedInput schema / examples
      Added value: +[
+  {
+    "_apiKey": "your-nba-api-key",
+    "query": "LeBron James"
+  },
+  {
+    "_apiKey": "your-nba-api-key",
+    "limit": 5,
+    "query": "Luka"
+  }
+]
  5. Changed2 schema fields changed
    • addedInput schema / properties / _apiKey
      Added value: +{
+  "description": "BallDontLie API key",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "query"
-]New value: +[
+  "query",
+  "_apiKey"
+]
  6. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Discloses exactly what is returned (position, height, weight, etc.) and what is NOT (per-game averages, career stats). Aligns with annotations (readOnly, idempotent, non-destructive). Adds context about API key tier and external endpoint limitation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-organized with examples, but slightly verbose with multiple example phrases. Each sentence adds value (purpose, exclusions, API key note). Could be more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's search nature and output schema existence, the description fully explains the return values, limitations, and prerequisites (API key). The warning about missing stats ensures the agent understands the scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters with descriptions (limit, query, _apiKey). The description adds no additional parameter-level details beyond the schema, but it does note that the free _apiKey works. Since schema coverage is 100%, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches NBA players by name on BallDontLie, lists returned fields (position, height, weight, etc.), and distinguishes itself by noting that per-season averages are not included. Examples like 'Find NBA player [name]' clarify usage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (search players by name) and when not (if stats needed, use /season_averages endpoint not exposed). Mentions free-tier _apiKey works and provides example queries. Differentiates from siblings by stating what data is absent.

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

All Nba toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources