get_golf_shot_data

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds a genuinely important caveat: requesting any hole >9 causes the filter to be silently dropped and all 18 holes returned. That silent-failure behavior directly changes how an agent should call the tool and cannot be derived from annotations or schema.

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?

It is a single dense sentence with heavy backticks and an internal re-join implementation detail, and it leads with the URL rather than the user-facing purpose. The critical >9 caveat is buried mid-sentence rather than front-loaded, though little is outright 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?

For a two-parameter read-only tool with no output schema, the description covers the parameter behavior and the one surprising failure mode thoroughly. It omits what the returned shot data actually contains and how to obtain a valid scorecardId, which are minor gaps given the annotations carry the safety profile.

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

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

Schema coverage is only 50% (holeNumbers has no schema description), and the description compensates well: comma/hyphen separators, whitespace stripping, the `-` re-join, the >9 drop, and the omit-to-get-all-18 default. Only scorecardId's provenance (where to obtain a valid id) is left unstated.

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 raw endpoint path (`/gcs-golfcommunity/api/v2/shot/scorecard/{scorecardId}/hole`) plus the verb 'GETs' makes it inferable that this fetches shot data for the holes of a golf scorecard, which is a specific resource. It never states the purpose in plain language and gives no differentiation from siblings like get_golf_scorecard, get_golf_summary, or get_golf_club_stats, so an agent must infer the boundary from the URL alone.

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 explains what happens when `holeNumbers` is omitted or contains values >9, but that is behavior, not guidance on when to choose this tool over get_golf_scorecard or get_golf_summary. There is no stated prerequisite (e.g. needing a scorecardId from another call) and no exclusion criteria.

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