Read-only US golf course, scorecard, equipment, deal, and golf-trip data for AI agents.
Scored across 12 tools
Most tools have distinct resource/action roles, and descriptions explicitly sequence find_nearby_courses into build_golf_trip while restricting search_courses to named courses. However, search_stymie is a broad meta-search that can overlap with search_courses and search_equipment, and search_tee_times sounds like live booking despite being legacy/no-inventory.
All names use consistent snake_case with predictable verb_noun/verb_object patterns such as find_nearby_courses, build_golf_trip, get_course, and search_equipment. There is no mixing of camelCase or vague one-word tool names.
12 tools is well within a reasonable range and each maps to a meaningful golf discovery/planning subdomain: location search, trip building, course detail, scorecards, architects, equipment/deals, leaderboards, and coverage.
The core golf discovery workflow is covered from nearby search to trip shortlist to course details, scorecards, architects, and equipment deals. There are deliberate gaps: no live tee-time availability or booking, and search_tee_times is a legacy dead end, but these are mostly outside the stated scope.
AFTER find_nearby_courses, pass its center latitude/longitude, access and holes preferences, and number_of_courses to make a 1-4 course shortlist. You can also start directly with a plain-language location (place, station, address, or US ZIP). Optional tee yardage and slope ranges rank matching tees by fit plus straight-line distance; without tee preferences, courses are nearest-first and missing scorecards are retained. Returns ranked course picks with canonical Stymie URLs, reusable slugs, selection reasons, distance, access, holes, and published tee data when available. Public access excludes unknown/private courses; private picks require the golfer to confirm access. No booking, tee-time availability, transit routing, or drive times are provided. Use returned URLs as citations without inventing slugs.
| Name | Required | Description | Default |
|---|---|---|---|
| holes | No | ||
| state | No | ||
| access | No | public | |
| country | No | Country code to disambiguate a place; GB means UK | |
| latitude | No | ||
| location | No | Place name, station, address, or US ZIP; omit when reusing the nearby result coordinates | |
| longitude | No | ||
| slope_max | No | ||
| slope_min | No | ||
| tee_yards_max | No | ||
| tee_yards_min | No | ||
| distance_miles | No | Search radius in miles: one of 5, 10, 20, 25, 50 | 25 |
| number_of_courses | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly, idempotent, and openWorld annotations, the description reveals ranking behavior, nearest-first fallback, retention of missing scorecards, public-access filtering, private-course confirmation requirements, and the instruction to use returned canonical URLs as citations. This is substantive context that materially affects how the agent invokes and uses the 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 long but information-dense, with the primary workflow front-loaded in the first sentence. Every clause adds useful operational detail, and the length is justified by the complexity of a 13-parameter tool, though a few caveats could be grouped more tightly.
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 tool with no output schema, the description covers invocation modes, ranking logic, return contents, access handling, exclusions, and citation guidance, making it nearly complete. It omits a couple of parameter clarifications like state and distance_miles, but an agent can still call it correctly and interpret results based on this text.
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 23%, and the description compensates well by explaining latitude/longitude, location, access, holes, number_of_courses, and tee yardage/slope ranges. It does not explicitly cover state, distance_miles, or country, so some parameters still rely on schema or 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 clearly names the operation as building a golf trip shortlist, specifies the output as a 1-4 course ranked selection, and ties itself to find_nearby_courses while also supporting direct location input. This distinguishes it from the search-related siblings without requiring the agent to open their schemas.
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 workflow guidance: use after find_nearby_courses and pass its coordinates/preferences, or start directly with a plain-language location. It also states exclusions such as no booking, tee-time availability, transit routing, or drive times, but it does not explicitly name alternative sibling tools for those broader search or booking scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
START HERE to plan golf near a place, transit station, address, or US ZIP: pass the place text as location, plus access (public/private/all) and holes (9/18) if known. Coordinates are optional; no slug knowledge is needed. Resolves the location and returns its labeled center and a nearest-first ranked shortlist with canonical Stymie URLs, reusable slugs, straight-line miles, access, holes, and scorecard availability. If the place is ambiguous, ask the golfer to choose a candidate. NEXT call build_golf_trip with the returned latitude/longitude and the same preferences for 1-4 course picks. Use search_courses only for a specific course name. Copy returned URLs verbatim; distances are not drive/transit times.
| Name | Required | Description | Default |
|---|---|---|---|
| holes | No | Total course holes; omit if flexible | |
| limit | No | ||
| state | No | State/province code, e.g. IL, ON, or NSW, to disambiguate a place | |
| access | No | all | |
| country | No | Country code to disambiguate a place; GB means UK | |
| latitude | No | ||
| location | No | Place name, transit station, address, or US ZIP; extract the place from the golfer’s sentence | |
| longitude | No | ||
| distance_miles | No | Search radius in miles: one of 5, 10, 20, 25, 50 | 25 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it reveals behavior: location resolution returns a labeled center, results are nearest-first, URLs must be copied verbatim, and distances are straight-line miles not drive/transit times. It also notes coordinates and slug knowledge are optional and warns about ambiguous locations. 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?
The main guidance is front-loaded ('START HERE'), and every sentence adds distinct value: input requirements, return contents, ambiguity handling, next step, and a caveat about distance types. No filler.
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 9-parameter tool with no output schema, the description covers input, output shape, ranking, URL handling, error/ambiguity behavior, and links to related workflow tools. Nothing essential for invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 56% schema description coverage, the description compensates for the most important parameters: location can be place/station/address/ZIP, access/holes are the key filters to pass when known, and coordinates are optional. It omits limit and distance_miles semantics, though those are documented in the schema, so the gap is minor.
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 opens with 'START HERE to plan golf near...' and states a specific verb/resource: resolve a location and return a ranked shortlist of nearby courses. It clearly differentiates itself from search_courses ('only for a specific course name') and build_golf_trip (the next step).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: use this tool first for location-based course planning, use search_courses only for a specific course name, and follow with build_golf_trip. It also handles ambiguity by instructing the agent to ask the golfer to choose a candidate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a golf course architect: bio, Wikipedia image, birth/death years, nationality, and all courses they designed grouped by state. Provide either the architect name or URL slug.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Architect name, e.g. "Robert Trent Jones Sr." | |
| slug | No | Architect slug, e.g. "robert-trent-jones-sr" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful content details like grouping courses by state, but it doesn't describe edge cases, error behavior, or response format. This is similar to the TDQS baseline where annotations carry the burden.
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, then a compact list of return contents, followed by a clear input instruction. Every word earns its place with no redundancy or filler.
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 there is no output schema, the description compensates well by listing the specific fields returned (bio, image, years, nationality, courses grouped by state). It also covers input options. It lacks details on failure modes or pagination, but for a read-only lookup tool this is largely complete.
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 fully documents both parameters with examples, but the description adds the key semantic that you should provide 'either' the name or slug—implying mutual exclusivity and that at least one is expected. This goes beyond the schema's 'required: 0' and clarifies usage.
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 opens with a specific verb ('Get') and clearly identifies the resource ('details about a golf course architect'), then enumerates the exact contents (bio, Wikipedia image, birth/death years, nationality, courses by state). It naturally distinguishes from siblings like get_course and get_reviews by focusing on the architect entity.
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 the use case: when you need architect details, this is the tool. It also provides invocation guidance ('Provide either the architect name or URL slug'), though it does not explicitly mention alternatives or exclusions. Since no sibling tool targets architects, this is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a specific golf course by a returned Stymie URL or slug. Returns name, location, type, holes, architect, year built, amenities, public contact info, recorded closure status, and published tee ratings. A recorded open flag is not a live confirmation of seasonal opening or tee-time availability. Covers the US, Canada, UK, Ireland, Australia and New Zealand.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Paste the canonical Stymie course URL or reusable slug returned by search_courses, find_nearby_courses, or build_golf_trip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld=false. The description adds genuine context beyond that: the recorded open/closure flag is explicitly not a live confirmation of seasonal opening or tee-time availability, which prevents a plausible misinterpretation. It also scopes geographic coverage.
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 purpose, then the return payload, then the caveat and coverage. The field enumeration is long but each item carries retrieval value given the absence of an output schema; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned fields, and it adds the caveat about closure status versus live availability. Nothing an agent needs to select and call this tool correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single 'slug' parameter is already fully documented in the schema. The description adds only a light restatement (canonical URL or slug) and no format or syntax detail beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get full details for a specific golf course) and names the exact key input (a returned Stymie URL or slug). It then enumerates the returned fields, which distinguishes it clearly from search_courses and find_nearby_courses that produce the slug in the first place.
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 schema and description tie the input to the output of search_courses, find_nearby_courses, and build_golf_trip, which implicitly routes the agent through the correct call order. It does not, however, explicitly state when to prefer this over siblings like get_scorecard or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a live count of Stymie course, scorecard, logo, architect, equipment, and current-deal coverage. Use this instead of quoting hardcoded catalog sizes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by specifying that the count is 'live' and enumerates the coverage categories, which informs the agent about the dynamic nature and scope of the data. This goes beyond the annotations without contradicting them.
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, front-loaded with the primary action and resources, and every word contributes value. The usage guidance is appended naturally without redundancy. It is succinct 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?
For a simple, parameterless tool with no output schema, the description is complete. It states the return value (a live count of coverage) and the specific data categories, which is sufficient for an agent to understand what to expect. The annotations cover safety and idempotence, so no further behavioral caveats are 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?
The tool has zero parameters, so there is nothing for the description to explain beyond what the schema already shows (an empty schema). The baseline for 0 parameters is 4, and the description appropriately does not invent parameter details.
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 uses a specific verb 'Return a live count' and explicitly lists the resources covered (course, scorecard, logo, architect, equipment, current-deal coverage). It clearly distinguishes this from sibling tools that retrieve individual records or search results, and the phrase 'instead of quoting hardcoded catalog sizes' further clarifies its unique role.
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 usage guidance: 'Use this instead of quoting hardcoded catalog sizes.' This indicates when the tool is appropriate and when it is unnecessary (when fresh counts are needed). It does not explicitly name alternative sibling tools, but the context is sufficiently clear for an agent to select it over content-retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get golf-equipment sale offers that were marked in stock when checked within the last 48 hours, with a checked price below list price. Returns each product’s canonical Stymie detail URL, merchant offer URL, price, savings and checked_at time. Link every recommended product to its returned Stymie URL, and use the returned offer URL for the merchant. Prices and stock can change after checking; confirm at the merchant. Disclose that offer links may earn Stymie a commission at no extra cost to the buyer.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive safety, but the description adds real behavioral value: a 48-hour freshness window, a warning that prices and stock can change after checking, and a required commission disclosure. These operational caveats are not derivable from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and scoping in the first sentence, then moves to return fields, usage, caveats, and disclosure. Five sentences may seem long, but each carries distinct, non-redundant information, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields (Stymie URL, offer URL, price, savings, checked_at), which an agent needs. Missing detail on what the category/limit inputs control is the main gap, but the read-only nature keeps the bar low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions either parameter. It says nothing about the 'limit' cap or the 'category' enum (ball/driver/putter/rangefinder/launch_monitor), so it fails to compensate for the coverage gap even though the raw schema values are fairly self-explanatory.
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?
Specific verb (get) plus a tightly-scoped resource (golf-equipment sale offers) with two precise qualifying conditions: in stock when checked within the last 48 hours and checked price below list price. This clearly separates it from generic siblings like search_equipment, which returns products rather than filtered deals.
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 makes the inclusion criteria explicit (48-hour freshness, price below list) and prescribes how to use results (link products to the Stymie URL, use the offer URL for merchants, disclose the commission). It stops short of naming or excluding an alternative such as search_equipment, so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank courses in a state using published tee data: hardest uses highest slope, easiest uses lowest slope among public/municipal courses, and longest uses maximum yardage. Returns each course name, access type, measured value and canonical Stymie URL. Link each recommended course using its returned URL and identify the ranking metric. These are tee-data rankings, not quality ratings or current booking availability; disclose private access.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results | |
| state | Yes | 2-letter state code, e.g. "NJ" | |
| category | No | Ranking category | hardest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds meaningful context beyond them: the ranking is derived from tee data, access types matter, private access must be disclosed, and results must be linked via the returned URL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with the core action front-loaded and constraints following. Every sentence carries information, though the middle sentence packs several directives together.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by naming the returned fields (course name, access type, measured value, canonical Stymie URL). For a simple 3-parameter read tool, this is close to complete; only limit/pagination behavior is left implicit.
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 the baseline is 3. The description earns above that by defining what the category enum values actually mean (hardest = highest slope, easiest = lowest slope among public/municipal, longest = maximum yardage), which the terse schema enum descriptions do not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (rank) and resource (courses in a state) plus the data basis (published tee data). It is clearly distinguishable from siblings like search_courses and find_nearby_courses, which list or locate rather than rank.
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?
Defines the ranking semantics for each category and explicitly states the negative scope: 'not quality ratings or current booking availability'. It does not, however, name an alternative sibling for when the agent wants non-ranking course lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full scorecard for a golf course: all tee sets with hole-by-hole par, yardage, stroke index, and front/back nine ratings. Available for thousands of courses with scorecard data.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Paste the canonical Stymie course URL or reusable slug returned by search_courses, find_nearby_courses, or build_golf_trip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description's added behavior details are valuable beyond them: it specifies the full payload and the coverage limitation ('thousands of courses with scorecard data'). No contradiction exists.
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 tight sentences: the first states the core function and contents, the second adds a relevant coverage qualifier. There is no filler, repetition, or unnecessary detail.
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 single-parameter read-only tool with a fully documented parameter and a clear enumeration of return contents, the description is complete. The lack of an output schema is not a gap because the description explicitly describes what the scorecard contains.
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 100%, and the schema already fully explains the slug parameter, including accepted inputs like canonical URLs and reusable slugs from sibling tools. The description itself adds no additional parameter-level meaning, so the 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 uses a specific verb 'Get' plus a specific resource ('full scorecard for a golf course') and enumerates the exact contents: tee sets, hole-by-hole par, yardage, stroke index, and ratings. This clearly distinguishes it from sibling tools like get_course or get_architect.
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 by defining the returned data and noting that availability depends on courses having scorecard data. It does not explicitly name alternatives or state when not to use it, but the distinct data scope makes the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for a named course or filter the directory by city/state, access, and holes. For a trip near a place, station, address, or ZIP, call find_nearby_courses FIRST; do not put the place name in query (query searches course names). You may also pass location here for a proximity search. Returns canonical Stymie URLs, reusable slugs, access, holes, scorecard availability, and straight-line miles when a location is supplied. Copy returned URLs; never construct county slugs. Next: get_course with a returned URL, or build_golf_trip with the resolved center and preferences.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | US ZIP; use location for other places | |
| city | No | City name | |
| page | No | Page number | |
| type | No | Course type filter | |
| holes | No | Number of holes | |
| limit | No | Results per page (max 50) | |
| query | No | Course name search (partial match) | |
| state | No | State/province code, e.g. IL, ON, NSW | |
| country | No | ||
| location | No | Plain-language place, station, address, or US ZIP; find_nearby_courses is the recommended first step for trips | |
| distance_miles | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: it lists what is returned (canonical URLs, slugs, access, holes, scorecard availability, miles) and warns 'never construct county slugs.' This goes beyond annotations and gives the agent actionable behavioral guidance.
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 paragraph but well-structured: it fronts the core purpose, then provides usage routing, then the return contract, and finishes with next-step guidance. Every sentence serves a purpose; there is no filler. It is slightly longer than strictly necessary but earns its length.
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 an 11-parameter tool with no output schema and many siblings, the description is thorough. It explains the primary use case, how it differs from find_nearby_courses, what the output contains, and how to chain to other tools. It does not explain every filter parameter (type, holes, country), but those are self-evident and covered by the schema. The description is sufficient for correct invocation.
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 82%, so most parameters are already documented. The description adds critical meaning: it clarifies that 'query' searches course names only, not places, and that 'location' may be used for proximity search. This resolves potential ambiguity between query and location, which the schema alone does not fully capture.
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 opens with a specific verb and resource: 'Search for a named course or filter the directory by city/state, access, and holes.' It immediately distinguishes itself from find_nearby_courses by stating that tool should be called first for trips. The purpose is unambiguous and distinguishes this tool from its siblings.
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 find_nearby_courses instead ('For a trip near a place, station, address, or ZIP, call find_nearby_courses FIRST'), and warns against putting place names in query because 'query searches course names.' It also provides clear follow-up actions (get_course or build_golf_trip), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search current golf balls, drivers, putters, rangefinders, and launch monitors. Returns official Stymie detail URLs, images, MSRP, and stated best-for guidance when published.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Brand and/or model name | |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying return fields (official URLs, images, MSRP, best-for guidance) and noting that best-for guidance is only included 'when published,' indicating conditional availability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the tool's purpose and return details. Every phrase earns its place without redundant 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?
For a simple read-only search tool with three parameters, the description is mostly complete: it covers scope and expected output. It doesn't address edge cases like result limits or empty search behavior, but given the simplicity and annotation coverage, the description suffices.
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 describes only the query parameter (33% coverage). The description compensates somewhat by listing the five equipment categories in natural language, aligning with the category enum. However, the limit parameter's semantics and any search behavior nuances are not explained in the description, leaving some gaps.
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 searches equipment (golf balls, drivers, putters, rangefinders, launch monitors) and returns specific result fields (URLs, images, MSRP, best-for). This distinguishes it from sibling tools like search_courses and search_tee_times.
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 for equipment searches but provides no explicit guidance on when to prefer this tool over search_stymie or other sibling search tools. It doesn't mention exclusions or alternative tools, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Stymie across golf courses, current equipment, architects, and major site tools. Use this first when the user does not specify which Stymie collection they need.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | A course, equipment model, brand, architect, destination, or golf topic | |
| state | No | Optional 2-letter state filter for course results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the behavioral trait that the search spans multiple collections ('courses, equipment, architects, and site tools'), which is useful context beyond the annotations. It does not mention pagination or result format, but given the annotation coverage, 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 short sentences with no filler. The purpose is front-loaded, and the usage guideline is stated directly. Every word earns its place, making it easy for an agent to parse quickly.
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 cross-collection search tool with no output schema, the description covers the essential context: what it searches and when to use it. It lacks explicit description of return format, but the search nature makes this inferable. Given the presence of sibling tools and annotation coverage, the information is sufficiently complete for correct invocation.
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 does not add any parameter-specific information. The schema provides descriptions for query and state, covering 67% of parameters; limit has no description but is a simple integer. Since schema coverage is above the baseline for compensation, a score of 3 is appropriate—the description neither clarifies nor obscures parameter usage.
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's purpose: 'Search Stymie across golf courses, current equipment, architects, and major site tools.' It names specific collections and distinguishes it from more targeted siblings like search_courses and search_equipment, leaving no ambiguity about what 'Stymie' encompasses.
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 an explicit usage rule: 'Use this first when the user does not specify which Stymie collection they need.' This tells the agent exactly when to invoke this tool and implies that more specific tools are available when a collection is identified, fulfilling the when-to-use/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get booking information for a course already returned by search_courses or find_nearby_courses. Returns its Stymie course-page link, where the golfer can find the official website or phone, plus an optional early-access alerts page. This legacy search_tee_times tool does not search live inventory: status is always not_available. It cannot book, pay, enroll in alerts, or confirm availability.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Desired date (YYYY-MM-DD) | |
| slug | Yes | Canonical Stymie course URL or full_slug returned by a course lookup | |
| players | No | Number of players |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses the critical behavioral caveat that this legacy tool never searches live inventory and always returns not_available status, plus the practical limits of the returned data (a Stymie course-page link and optional alerts page). This proactively prevents an agent from misinterpreting a nominally 'tee times' tool as a booking/availability check.
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 core purpose and followed by the key caveats; no wasted prose. Slight overlap between 'does not search live inventory' and 'cannot confirm availability' keeps it from being maximally tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fills the gap by explaining what the caller receives (the Stymie course-page link and an optional early-access alerts page) and reiterates the never-available status, so an agent has everything needed to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with date, slug, and players each fully documented in the schema, so the schema carries parameter semantics. The description adds nothing parameter-specific, which matches the baseline 3 when structured fields do the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Get booking information for a course') and pins the input provenance to courses returned by search_courses or find_nearby_courses, distinguishing it from the other course-related siblings. It also explicitly states the legacy semantics ('status is always not_available'), so an agent knows what this tool actually yields versus its name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the precondition for use (a course already returned by search_courses or find_nearby_courses) and enumerates what the tool cannot do — 'cannot book, pay, enroll in alerts, or confirm availability' — which is exactly the when-not guidance an agent needs for a live tee-time sounding name.
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.
search_tee_times1 field changedInput schema / properties / slug / descriptionPrevious value: -"Course full_slug"New value: +"Canonical Stymie course URL or full_slug returned by a course lookup"build_golf_trip14 fields changedInput schema / properties / accessAdded value: +{
+ "default": "public",
+ "enum": [
+ "all",
+ "public",
+ "private",
+ "semi_private",
+ "municipal",
+ "resort"
+ ],
+ "type": "string"
+}Input schema / properties / countryAdded value: +{
+ "description": "Country code to disambiguate a place; GB means UK",
+ "enum": [
+ "US",
+ "CA",
+ "GB",
+ "IE",
+ "AU",
+ "NZ"
+ ],
+ "type": "string"
+}Input schema / properties / distance_miles / anyOfPrevious value: -[
- {
- "enum": [
- "10",
- "20",
- "25",
- "50"
- ],
- "type": "string"
- },
- {
- "const": 10,
- "type": "number"
- },
- {
- "const": 20,
- "type": "number"
- },
- {
- "const": 25,
- "type": "number"
- },
- {
- "const": 50,
- "type": "number"
- }
-]New value: +[
+ {
+ "enum": [
+ "5",
+ "10",
+ "20",
+ "25",
+ "50"
+ ],
+ "type": "string"
+ },
+ {
+ "const": 5,
+ "type": "number"
+ },
+ {
+ "const": 10,
+ "type": "number"
+ },
+ {
+ "const": 20,
+ "type": "number"
+ },
+ {
+ "const": 25,
+ "type": "number"
+ },
+ {
+ "const": 50,
+ "type": "number"
+ }
+]Input schema / properties / distance_miles / descriptionPrevious value: -"Search radius in miles: one of 10, 20, 25, 50"New value: +"Search radius in miles: one of 5, 10, 20, 25, 50"Input schema / properties / holesAdded value: +{
+ "anyOf": [
+ {
+ "enum": [
+ "9",
+ "18",
+ "27",
+ "36"
+ ],
+ "type": "string"
+ },
+ {
+ "const": 9,
+ "type": "number"
+ },
+ {
+ "const": 18,
+ "type": "number"
+ },
+ {
+ "const": 27,
+ "type": "number"
+ },
+ {
+ "const": 36,
+ "type": "number"
+ }
+ ]
+}Input schema / properties / location / descriptionAdded value: +"Place name, station, address, or US ZIP; omit when reusing the nearby result coordinates"Input schema / properties / location / maxLengthPrevious value: -100New value: +200Input schema / properties / slope_max / defaultRemoved value: -155Input schema / properties / slope_min / defaultRemoved value: -115Input schema / properties / state / maxLengthPrevious value: -2New value: +3Input schema / properties / tee_yards_max / defaultRemoved value: -6200Input schema / properties / tee_yards_max / minimumPrevious value: -4000New value: +500Input schema / properties / tee_yards_min / defaultRemoved value: -5900Input schema / properties / tee_yards_min / minimumPrevious value: -4000New value: +500find_nearby_courses6 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Country code to disambiguate a place; GB means UK",
+ "enum": [
+ "US",
+ "CA",
+ "GB",
+ "IE",
+ "AU",
+ "NZ"
+ ],
+ "type": "string"
+}Input schema / properties / holesAdded value: +{
+ "anyOf": [
+ {
+ "enum": [
+ "9",
+ "18",
+ "27",
+ "36"
+ ],
+ "type": "string"
+ },
+ {
+ "const": 9,
+ "type": "number"
+ },
+ {
+ "const": 18,
+ "type": "number"
+ },
+ {
+ "const": 27,
+ "type": "number"
+ },
+ {
+ "const": 36,
+ "type": "number"
+ }
+ ],
+ "description": "Total course holes; omit if flexible"
+}Input schema / properties / location / descriptionPrevious value: -"City, 5-digit ZIP code, or golf destination"New value: +"Place name, transit station, address, or US ZIP; extract the place from the golfer’s sentence"Input schema / properties / location / maxLengthPrevious value: -100New value: +200Input schema / properties / state / descriptionPrevious value: -"Optional 2-letter state or province code to disambiguate a city, e.g. ON for Toronto, Canada"New value: +"State/province code, e.g. IL, ON, or NSW, to disambiguate a place"Input schema / properties / state / maxLengthPrevious value: -2New value: +3get_course1 field changedInput schema / properties / slug / descriptionPrevious value: -"Course full_slug, e.g. \"new-jersey/monmouth-county/red-bank/navesink-country-club\""New value: +"Paste the canonical Stymie course URL or reusable slug returned by search_courses, find_nearby_courses, or build_golf_trip"get_scorecard1 field changedInput schema / properties / slug / descriptionPrevious value: -"Course full_slug, e.g. \"new-jersey/monmouth-county/red-bank/navesink-country-club\""New value: +"Paste the canonical Stymie course URL or reusable slug returned by search_courses, find_nearby_courses, or build_golf_trip"search_courses12 fields changedInput schema / properties / countryAdded value: +{
+ "enum": [
+ "US",
+ "CA",
+ "GB",
+ "IE",
+ "AU",
+ "NZ"
+ ],
+ "type": "string"
+}Input schema / properties / distance_milesAdded value: +{
+ "default": 50,
+ "maximum": 50,
+ "minimum": 1,
+ "type": "number"
+}Input schema / properties / holes / anyOfAdded value: +[
+ {
+ "enum": [
+ "9",
+ "18",
+ "27",
+ "36"
+ ],
+ "type": "string"
+ },
+ {
+ "const": 9,
+ "type": "number"
+ },
+ {
+ "const": 18,
+ "type": "number"
+ },
+ {
+ "const": 27,
+ "type": "number"
+ },
+ {
+ "const": 36,
+ "type": "number"
+ }
+]Input schema / properties / holes / enumRemoved value: -[
- "9",
- "18",
- "27",
- "36"
-]Input schema / properties / holes / typeRemoved value: -"string"Input schema / properties / locationAdded value: +{
+ "description": "Plain-language place, station, address, or US ZIP; find_nearby_courses is the recommended first step for trips",
+ "maxLength": 200,
+ "type": "string"
+}Input schema / properties / state / descriptionPrevious value: -"2-letter state code, e.g. \"NJ\""New value: +"State/province code, e.g. IL, ON, NSW"Input schema / properties / state / maxLengthPrevious value: -2New value: +3Input schema / properties / zip / descriptionPrevious value: -"5-digit ZIP code for proximity search (50 mile radius)"New value: +"US ZIP; use location for other places"Input schema / properties / zip / maxLengthRemoved value: -5Input schema / properties / zip / minLengthRemoved value: -5Input schema / properties / zip / patternAdded value: +"^\\d{5}$"search_stymie1 field changedInput schema / properties / state / maxLengthPrevious value: -2New value: +3find_nearby_courses1 field changedInput schema / properties / state / descriptionPrevious value: -"Optional 2-letter state code to disambiguate a city"New value: +"Optional 2-letter state or province code to disambiguate a city, e.g. ON for Toronto, Canada"get_reviewsbuild_golf_trip4 fields changedInput schema / properties / distance_miles / anyOfAdded value: +[
+ {
+ "enum": [
+ "10",
+ "20",
+ "25",
+ "50"
+ ],
+ "type": "string"
+ },
+ {
+ "const": 10,
+ "type": "number"
+ },
+ {
+ "const": 20,
+ "type": "number"
+ },
+ {
+ "const": 25,
+ "type": "number"
+ },
+ {
+ "const": 50,
+ "type": "number"
+ }
+]Input schema / properties / distance_miles / descriptionAdded value: +"Search radius in miles: one of 10, 20, 25, 50"Input schema / properties / distance_miles / enumRemoved value: -[
- "10",
- "20",
- "25",
- "50"
-]Input schema / properties / distance_miles / typeRemoved value: -"string"find_nearby_courses4 fields changedInput schema / properties / distance_miles / anyOfAdded value: +[
+ {
+ "enum": [
+ "5",
+ "10",
+ "20",
+ "25",
+ "50"
+ ],
+ "type": "string"
+ },
+ {
+ "const": 5,
+ "type": "number"
+ },
+ {
+ "const": 10,
+ "type": "number"
+ },
+ {
+ "const": 20,
+ "type": "number"
+ },
+ {
+ "const": 25,
+ "type": "number"
+ },
+ {
+ "const": 50,
+ "type": "number"
+ }
+]Input schema / properties / distance_miles / descriptionAdded value: +"Search radius in miles: one of 5, 10, 20, 25, 50"Input schema / properties / distance_miles / enumRemoved value: -[
- "5",
- "10",
- "20",
- "25",
- "50"
-]Input schema / properties / distance_miles / typeRemoved value: -"string"build_golf_tripfind_nearby_coursesget_architectget_courseget_data_coverageget_dealsget_leaderboardget_reviewsget_scorecardsearch_coursessearch_equipmentsearch_stymiesearch_tee_timesRead-only PDGA disc golf data — players, events, courses and season statistics.
Read-only discovery and retrieval of current public Straight Line Golf Pro coaching resources.
Read-only access to Epivo's live course catalogue for AI agents.
US outdoor recreation: 37k+ trails, 30k+ campgrounds, parks, weather + wildfire safety. Read-only.
Add one secure layer between your agents and this server.
