Stymie Golf

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

The description adds process details beyond annotations, such as matching real tee yardage and slope data and balancing fit vs. travel distance. It also discloses a limitation (separate verification required), which is valuable behavioral context. No contradiction with read-only 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 only two sentences long and communicates the core function efficiently. However, words like 'transparent' and 'fit' are vague and could be replaced with more concrete terms without adding 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 a complex tool with 10 optional parameters and no output schema, the description gives a reasonable high-level understanding but omits return value details and parameter semantics. It adequately sets expectations for planning but leaves critical usage 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 description coverage is 0%, and the description only vaguely mentions location types (city, ZIP, coordinate) and course count. It does not explain the 10 parameters, their constraints, or how to combine them, so the description fails to compensate for the missing schema documentation.

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 builds a one- to four-course public-access golf trip based on a location, with specific verb and resource. It distinguishes from sibling tools by focusing on trip construction rather than course discovery, though it doesn't explicitly name alternatives.

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 provides an explicit boundary: tee-time availability and drive times must be verified separately. This tells the user what the tool does not do, offering clear context for when to use it. It lacks named alternatives but the guidance is useful.

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?

The annotations already declare read-only and idempotent behavior, so the bar is lower. The description adds useful behavioral context by listing the specific return fields (exact mileage, logo availability, scorecard availability, maximum slope), which goes beyond the structured metadata. It does not disclose potential edge cases like coordinate pairing requirements, but is not misleading.

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 succinct sentences, front-loaded with the core action and scope, and every phrase adds value. 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?

The tool has 7 parameters, no required fields, and no output schema, so the description carries a significant burden. It covers the primary search concept and output fields, but omits key operational details such as parameter defaults (distance_miles, limit), how coordinates are supplied, and the full set of access filter values. This is adequate but leaves clear 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 description coverage is only 29%, so the description must compensate. It does clarify that 'location' can be a city, ZIP, destination, or coordinate and mentions access-related filters, but it leaves out the 'limit' parameter and does not explain that 'state' disambiguates cities or that latitude/longitude likely need to be paired. It partially compensates but not fully.

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 ('Find') with a clear resource ('golf courses') and precisely defines the scope ('within an exact distance of a city, ZIP code, destination, or coordinate'). It also mentions filters and return details, which distinguishes it from broader sibling tools like search_courses.

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 this tool: when you need courses near a specified location or coordinate. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it misses the higher bar for explicit exclusions.

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, 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.

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

Annotations already cover the read-only, idempotent, and non-destructive nature. The description adds valuable context by enumerating the returned fields (name, location, type, holes, architect, etc.), giving the agent a clear expectation of the response content without needing an output 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?

A single, front-loaded sentence states the purpose and then lists return fields efficiently. Every word contributes to understanding, 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?

Despite lacking an output schema, the description fully discloses the expected return payload by listing the key data categories. The tool is simple (one parameter, no nested objects), and the description covers all essential aspects for correct invocation and response interpretation.

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 input schema already provides full coverage of the single parameter 'slug' with a detailed example. The description only repeats 'by its URL slug' and adds no additional semantic meaning, so a baseline score of 3 is appropriate given the schema's completeness.

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 a specific verb ('Get'), resource ('full details for a specific golf course'), and identifier ('by its URL slug'). It distinguishes itself from sibling tools like search_courses and find_nearby_courses by focusing on a direct lookup by unique slug.

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 phrase 'by its URL slug' clearly indicates that this tool is used when you already have the slug and need comprehensive details. It does not explicitly mention alternatives or when-not-to-use, but the context is clear for a typical get-by-id pattern.

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, 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.

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: offers must be checked within 48 hours, be in stock, and have a price below list. It also transparently discloses that links may be affiliate links, providing additional insight beyond the schema and 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 three sentences long, front-loaded with the core purpose, and every sentence adds value: what the tool returns, the freshness/availability criteria, and the affiliate link disclosure. There is no redundancy or filler, making it highly efficient.

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 simplicity, the description is fairly complete: it states what is returned and the key constraints. However, there is no output schema and the description does not describe the result shape (e.g., fields like price, link, or product name). Since the tool is straightforward and annotations cover safety, the missing return-shape details are a minor gap rather than a critical one.

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 has 2 parameters (limit, category) with 0% description coverage, so the description carries the burden of explaining them. The description mentions "golf equipment" but does not explain how limit controls the number of results or how category filters deals. The schema's enum for category offers some inherent meaning, but the description does not compensate for the lack of parameter-level documentation.

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-resource combination, "Get currently verified sale offers for golf equipment," clearly identifying the tool's function and domain. It distinguishes itself from sibling tools like search_equipment by emphasizing "verified sale offers" and the specific filtering criteria, making its unique purpose evident.

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 this tool is appropriate by specifying that it returns only verified, in-stock sale offers below list price. It does not explicitly name alternatives or state when not to use it, but the criteria strongly imply use cases involving deal discovery rather than general equipment search.

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 read-only/idempotent behavior, so the description adds value by defining category semantics (e.g., 'easiest' is public-only) and the metrics used (slope, yardage). This goes beyond the schema's enum labels.

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 main purpose, and every clause adds value. No filler or redundant wording.

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 read-only leaderboard tool with three simple parameters, the description covers purpose, usage scenarios, and category definitions. It doesn't specify the return format, but the low complexity and lack of output schema make this acceptable.

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 covers 100% of parameters, but the description enriches the meaning of the 'category' parameter by explaining what each value represents. It also gives a state code example, adding practical context.

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 top golf courses ranked by category (hardest, easiest, longest), with specific criteria for each. This distinguishes it from siblings like search_courses or get_course by emphasizing leaderboard-style ranking.

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 a concrete use case ('hardest course in NJ' questions) and explains the category criteria, making it clear when to use this tool. It doesn't explicitly name alternatives, but the context is well-defined.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail by specifying the return fields (star ratings, sub-ratings, review text, tee played, reviewer handicap), which is especially helpful because there is no output schema. 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 two sentences, front-loaded with the core purpose, and includes only essential details about return values. There is no redundancy or fluff, making it highly efficient.

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 tool with no output schema, the description adequately explains both the action and the expected return content. It lacks details about ordering, pagination, or edge cases (e.g., no reviews found), but given the low complexity and strong schema coverage, it is reasonably 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?

Both parameters (slug and limit) are already fully described in the input schema with 100% coverage. The description does not add any additional semantic detail about the parameters themselves. This is an appropriate baseline since the schema carries the load.

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 action ('Get') and resource ('user reviews for a golf course'), and goes further to enumerate the returned data (ratings, sub-ratings, text, tee, handicap). This distinguishes it from siblings like get_course, which would provide course details rather than reviews.

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 no explicit guidance on when to use this tool vs alternatives, nor any exclusions. The specific 'reviews' scope makes its purpose unambiguous, but it does not mention when not to use it or point to sibling tools like search_tee_times. The usage context is implied rather than stated.

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?

With annotations already declaring read-only, non-destructive behavior, the description adds valuable context by detailing the output content and the limitation that scorecard data may not exist for all courses.

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 core purpose and followed by a brief note on availability. Every word contributes meaningful information with no redundancy.

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?

Since there is no output schema, the description usefully enumerates the returned data elements, giving the agent a solid understanding of the tool's output. It could mention edge cases or error responses, but the level of detail is adequate for a simple read-only 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?

The schema fully describes the sole parameter with an example, so the description adds no additional parameter semantics. Per the rubric, baseline 3 applies when schema coverage is high.

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 gets a full scorecard for a golf course, enumerating the specific content (all tee sets, hole-by-hole par, yardage, stroke index, ratings). This distinguishes it from sibling tools like get_course and get_reviews.

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 implicit usage context by focusing on scorecard data and noting availability for thousands of courses, but it does not explicitly discuss when to choose this tool over alternatives 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.

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by noting the 'live' nature of the data, listing return fields (location, access, holes, architect, scorecard availability, ratings), and explicitly stating that exact mileage is only for ZIP searches. This goes beyond 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 verb 'Search', and efficiently packs both search dimensions and return fields. No filler or redundant phrasing.

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 8 optional parameters with 100% schema coverage and strong annotations, the description covers the essential aspects: what is searched, what is returned, and the special ZIP-mileage behavior. Pagination is documented in the schema, so the description is complete enough for an agent to select and invoke the tool 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%, giving a baseline of 3. The description adds meaningful mappings from search dimensions to parameters (name, state, city, ZIP, access type, hole count) and clarifies that ZIP searches produce exact mileage, enriching the semantics of the zip parameter beyond the schema's raw description.

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 specifies the verb and resource: 'Search Stymie's live US golf-course directory' by name, state, city, ZIP, access type, or hole count. It clearly distinguishes this from sibling tools like get_course (single course) and find_nearby_courses (proximity focus), especially by noting directory-wide search and ZIP-specific mileage.

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 clearly implies when to use this tool: when searching the golf-course directory by various criteria, and it highlights that ZIP searches produce exact mileage. It does not explicitly state when not to use it or name alternatives, so it falls short of a perfect 5, but the context is sufficiently clear.

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, 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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. The description adds the multi-collection scope and first-use advisory, but does not detail how results are grouped, ordered, or returned. This is acceptable given annotation coverage, but not richer.

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 exactly two sentences, front-loaded with the action and scope, and both sentences carry useful information with no 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 search tool with three parameters and no output schema, the description provides purpose, scope, and usage guidance. It does not explicitly describe the return format or grouping, but annotations and the search context make it reasonably complete. Minor gap prevents a 5.

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 67% (query and state have descriptions; limit does not). The tool description adds context that the query can span multiple collections, but does not add meaning for limit or state beyond the schema. Baseline 3 applies because coverage exceeds 50%.

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 Stymie across multiple named collections (golf courses, equipment, architects, site tools) with an explicit verb and scope. It also distinguishes itself from sibling tools by saying to use it first when the user does not specify a collection.

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 tells the agent when to use this tool: 'Use this first when the user does not specify which Stymie collection they need.' It implies the alternative is collection-specific search tools but does not name them or list exclusions, so it falls short of a 5.

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?

The description goes beyond the annotations by explaining the current limitation (no real-time data) and the actual behavior (returns a link for alerts). This is transparent and helpful for setting expectations, with no contradiction to 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 two sentences, front-loaded with the core purpose, and each sentence adds essential information. No wasted words.

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?

The description explains the return behavior (a link for alerts) and the current state, which is adequate given the lack of an output schema. However, it doesn't clarify how date and players parameters affect the returned link, leaving some ambiguity about their role in the current implementation.

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 input schema provides descriptions for all three parameters (slug, date, players), so the schema covers semantics. The tool description itself adds no additional parameter context, so the baseline of 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 clearly states the tool searches for available tee times at a golf course, with a specific verb and resource. However, the caveat that real-time data is coming soon and it currently returns a link for alerts makes the immediate purpose less straightforward, though still clear.

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 context that this tool is not yet fully functional for real-time tee times and currently guides users to set up alerts. It doesn't explicitly mention alternatives like search_courses, nor when-not-to-use, so guidance 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.