get_golf_scorecard

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds non-obvious implementation behavior: hyphenated query parameter names and the quirk that `include-longest-shot-distance` must be sent as the literal string "true" rather than a boolean. It still says nothing about error behavior or response shape, so it is not a 5.

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 short sentence with no padding, so it is concise and front-loaded. However, the space is spent on transport details instead of the functional purpose, so the sentence does not fully earn its place as the primary description.

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 one-parameter read-only GET with no output schema, the description gives enough to construct the request, including the boolean-as-string quirk. It is incomplete in that it never explains what a scorecard contains, how it relates to sibling golf tools, or how to obtain the required scorecard id.

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% for the single `scorecardId` parameter, so the 3 baseline applies. The description goes beyond the schema by exposing additional query parameters (`scorecard-ids`, `include-longest-shot-distance`) that appear nowhere in the input schema, including the string-vs-boolean encoding quirk. It does not reconcile the plural `scorecard-ids` naming with the singular `scorecardId` schema field, which is a minor ambiguity.

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 only names the underlying REST path (`/gcs-golfcommunity/api/v2/scorecard/detail`) rather than stating in functional terms that it retrieves a single golf scorecard by id. It restates the tool name through a URL, and gives no clue how a 'scorecard detail' differs from get_golf_summary, get_golf_shot_data, or get_golf_club_stats.

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?

There is no when-to-use guidance and no mention of any alternative golf tool. An agent cannot tell from this text whether to call this or get_golf_summary/get_golf_shot_data for the same data, nor what prerequisites (e.g., needing a scorecard id from another call) exist.

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