Skip to main content
Glama
Open Golf Handicap MCP

Open Golf Handicap MCP

search_golfers

Read-onlyIdempotent

Look up active US golfers by name to retrieve GHIN numbers and current Handicap Indexes, then review matches by club and state before adding a golfer to the roster.

Instructions

Find golfers by name to get their GHIN number and current index. Needs a first name; add a last name and a 2-letter US state code (e.g. NC) to narrow it. Returns up to 25 active US golfers. Several people often share a name: show the matches (name, club, state) and let the user pick before saving anyone to the roster.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "firstName": "<firstName>"
    },
    "name": "search_golfers"
  }
}

Input Schema

NameRequiredDescriptionDefault
stateNo
lastNameNo
firstNameYes

Output Schema

NameRequiredDescriptionDefault
okYes
dataNo
errorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds real context they do not: scope is limited to active US golfers, results cap at 25, and duplicate names are common, which implies the caller must handle ambiguity rather than assume a single hit.

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

Conciseness5/5

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

Front-loads the core action and outcome, then adds narrowing rules and the disambiguation step in descending priority. Every sentence carries information; nothing is redundant with the schema or annotations.

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

Completeness4/5

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

With an output schema present, the description need not enumerate return fields, yet it still names what comes back (name, club, state). It covers the main edge case (shared names) but does not say what happens on zero matches or when more than 25 golfers match, which matters for a capped search.

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 description coverage is 0%, so the description carries the burden, and it does explain that firstName is mandatory while lastName and state narrow results, including a format example ('NC') for the state code. It does not clarify matching semantics for the name fields (exact vs prefix vs partial), leaving a meaningful gap despite the regex patterns in the schema.

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?

States a specific verb and resource ('Find golfers by name') plus the payoff ('get their GHIN number and current index'). This clearly separates it from roster-reading siblings like get_saved_golfers or get_golfer_handicap, which operate on already-saved players.

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

Usage Guidelines4/5

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

Gives explicit narrowing strategy (required first name, optional last name and 2-letter state) and a workflow rule: show matches and let the user pick before saving anyone to the roster. It stops short of stating when to avoid this tool (e.g. for already-saved golfers, use get_saved_golfers instead), so it is strong but not fully exhaustive.

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