PGA Golf

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

The description adds meaningful behavioral context beyond the annotations: it discloses that a continuation URL is returned, that a confirmation code may be included for automatic bookings, and that offeringId must never be shown to the user. These details help the agent understand the response flow and handle sensitive identifiers correctly. The annotations only indicate non-readonly, so this extra context is valuable.

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 concise and well-structured, with a clear opening statement followed by three relevant bullet points. Every sentence adds value, and there is no redundant or filler content.

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 the tool's complexity (booking with different student types, internal IDs, and follow-up URLs), the description covers key aspects: the internal ID privacy rule, the continuation URL, and conditional confirmation codes. The existence of an output schema reduces the need to explain return values. It could mention prerequisites like checking availability, but the sibling tools imply that workflow.

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 already covers most parameter meanings (student details, startDateTime format, offeringId as internal record ID). The description adds crucial usage semantics by emphasizing that offeringId is internal and must never be displayed or mentioned to the user, and by clarifying that a continuation URL will be returned. This goes beyond schema descriptions and helps with correct invocation.

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 function: requesting to book a golf lesson for a specific coach's offering. It uses a specific verb and resource, and the context of booking a lesson distinguishes it from sibling tools like get_golf_coach_availability and search_golf_coaches.

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 context for when to use the tool—when booking a lesson for a specific offering—and what to do after calling it (direct the user to the continuation URL). It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous enough that an agent can select it appropriately alongside the sibling tools.

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

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

Annotations already declare `readOnlyHint: true` and `destructiveHint: false`, clearly signaling this is a read-only, non-destructive operation. The description adds value by clarifying it retrieves 'available lesson times' and 'offering details', and it discloses the operational caveat that the slug and offeringId are internal identifiers not to be shown. No contradictions with annotations are present.

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 extremely concise, consisting of only four sentences with no waste. Critical information is front-loaded: the purpose is stated in the first sentence, with usage constraints and security rules following immediately. Every sentence earns its place by addressing a distinct aspect (purpose, use case, prerequisites, security constraint).

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 that the input schema has 100% coverage, an output schema exists, and annotations fully cover the tool's safety profile, the description is complete. The output schema presumably defines the return shape for availability and offering details, so the description does not need to expand on that. The description effectively sets context on when to use the tool and how to handle internal identifiers, leaving no gaps.

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%, with both `slug` and `offeringId` having detailed descriptions in the schema. The tool description does not add additional parameter-level information beyond what the schema provides, which aligns with the baseline score of 3. The description does inform usage context for the parameters (e.g., using slug from prior search results), but that is more about usage guidelines than parameter semantics.

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 retrieves 'offering details and available lesson times for one specific coach'. It uses a specific verb ('Retrieve') and resource ('offering details and available lesson times'), and the context of 'one specific coach' effectively distinguishes it from sibling tools like `search_golf_coaches` which searches for coaches rather than their availability.

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 explicitly states when to use this tool ('when the user asks for schedule, openings, or available times for a known coach') and provides clear guidance on what to do if the coach is not yet selected, directing the agent to call `search_golf_coaches` or reuse results from `search_golf_programs`. It also notes that internal identifiers (slug and offeringId) 'must never be shown or mentioned to the user', which is a crucial usage constraint.

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

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

Annotations already declare readOnlyHint=true (safe, read-only operation). The description adds valuable context beyond annotations: ordering by proximity, pagination behavior, that results are capped at 2 program teasers, and that internal record identifiers must be hidden from users. No contradictions are present.

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 front-loaded with the essential purpose, then usage guidelines, then behavioral details. It is reasonably concise for the amount of guidance provided, though the repeated sibling references could be slightly tighter. Every sentence adds value.

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 the presence of an output schema and good annotations, the description covers all necessary aspects: what the tool does, when to use it vs siblings, ordering, pagination, and handling of internal identifiers. No gaps remain for the agent to make correct decisions.

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% with good descriptions for all parameters. The description amplifies understanding by clarifying that searchLocation is required and provides guidance on default searchRadius (25 miles unless user requests otherwise). It also explains the paginationCursor usage appropriately.

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 ('Search') and resource ('qualified PGA golf coaches listed on pga.com/coach'), clearly distinguishing its purpose from siblings. It explicitly states the required location and that results include profile info, pricing, and program teasers.

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 explicit when-to-use guidance ('when the user asks to find, browse, or compare coaches for private lessons'), when-not-to-use alternatives ('use search_golf_programs for clinics/camps/classes; use get_golf_coach_availability for coach availability'), and even advises on presenting results to the user.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the tool is safe. The description adds rich behavioral details: discovery uses nearby PGA Coach profiles, loads up to 30 programs per coach in a 180-day window via batched GraphQL request, pagination cursor behavior, ordering by start instant, and the inclusion of top-level `coaches` and `facilities` arrays. No contradictions 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 description is well-structured with front-loaded purpose, then usage guidance, then behavioral details, and finally pagination instructions. Each sentence is justified. It is slightly longer than necessary but remains clear and non-redundant. A minor improvement would be to trim redundant explanations of the pagination cursor already covered in the schema.

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 the complexity (3 parameters, output schema exists, annotations present), the description covers purpose, usage, behavioral mechanics, pagination, and presentation instructions. It explains the internal discovery process, pagination reuse, and directs users to program URLs. No gaps are evident for an AI agent to correctly select and invoke the tool.

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 baseline is 3. The description adds value for `searchLocation` by specifying accepted formats (city/state, ZIP, address, lat/lng). For `searchRadius` and `paginationCursor`, the schema already provides detailed descriptions; the description reinforces pagination behavior but does not add new parameter-specific semantics. Overall, it provides meaningful extra context beyond the schema.

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 for 'upcoming public PGA Coach programs (clinics, camps, classes, and other group events) near a location.' It explicitly distinguishes from private lessons and names the sibling tool `search_golf_coaches` for that purpose. The verb 'search' and resource 'golf programs' are specific and unambiguous.

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 explicit when-to-use guidance: 'Use this tool when the user asks to find programs, clinics, camps, classes, or group events — not private one-on-one lessons.' It also gives a clear alternative: 'For private lesson coaches, use `search_golf_coaches` instead.' This covers both positive and negative use cases.

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