GolfCore

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful non-obvious behavior: keys are returned as prefixes only, never secrets, and paid plans have no monthly cap unless the person sets one.

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-loaded and clear, but the full pricing schedule (dollar amounts, per-1,000 overage rates) is longer than needed to select or invoke a read-only account tool. That block serves interpretation of the returned plan, not invocation, and crowds out more actionable guidance.

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 carries the return-value burden and does so by listing the fields returned and the key-prefix caveat. It also handles the empty state. Minor gaps remain around error cases for an invalid account_id, but nothing essential is missing for a one-parameter read.

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% and the single parameter is already documented as optional with 'omit to list all'. The description's 'or read one with its plan...' restates that branch rather than adding syntax or edge-case meaning, 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 ('list the API accounts ... or read one') and enumerates exactly what a read returns: plan, usage, monthly cap, key prefixes. It also distinguishes itself from siblings by naming the api_ family and its role as the prerequisite lookup.

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 says 'Use it before the other api_ tools to get account_id and key_id', giving both the ordering and the reason. It also covers the no-account case and points to the signup URL, so the agent knows what to do when the tool returns nothing 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?

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds real context: default no-cap billing behavior, that requests are refused after the cap until the month resets, and that the cost impact should be confirmed. It stops short of describing the response or whether lowering an existing cap is reversible mid-month.

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?

Every sentence carries load, but the description leads with background on default billing before naming the tool's own action, so the core verb lands in sentence two. Dense and efficient overall, just not maximally front-loaded.

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 idempotent mutation with no output schema, the description covers defaults, the effect of the cap, how to remove it, where the baseline comes from, and the human-confirmation requirement. An agent has everything needed to call 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 coverage is 100%, so both parameters are already documented. The description adds meaning beyond the schema: units=null removes the cap, the cap must start at the plan's included requests, and account_id comes from api_account. Useful, though the minimum:1 vs null distinction is largely in 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 states a specific verb (sets/removes) and resource (the monthly API request cap) and explains both outcomes — cap applied or cap removed when units is null. It also distinguishes itself from api_account, which is where the included-request baseline is read rather than written.

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 when the tool applies (Starter/Pro, which otherwise bill overage without limit), the trigger for removal (units is null), where to source the starting value (api_account), and adds an explicit prerequisite to confirm the number and cost with a person first. Alternatives and exclusions are covered.

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 cover the safety profile (readOnly=false, destructive=false, non-idempotent), so the bar is lower. The description still adds genuinely useful disclosure beyond them: the secret is returned only once and must not be placed in chat logs, code, or client-side code.

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 short sentences, front-loaded with the action and outcome, then the handling constraint. Every sentence contributes; only the chat-log warning is slightly tangential to tool invocation.

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 correctly discloses the key return value ('Returns the secret once'). Combined with the parameters and annotations, an agent has enough to invoke it correctly, though auth/permission requirements are unstated.

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 schema already documents name, expiry (with default and enum), and account_id. The description adds no syntax or format detail beyond the 'confirm the name' hint, so 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 ('Create') and resource ('GolfCore Course Data API key') scoped to the signed-in person's account, which is clear on its own. It does not explicitly contrast with siblings like api_revoke_key, though the create/revoke inverse is self-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?

It gives a workflow prerequisite ('Confirm the name with the person first') and downstream handling instructions, but never states when this tool should or should not be used relative to alternatives. Usage is implied rather than spelled out.

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 destructiveHint=true and idempotentHint=true, yet the description adds genuinely new behavior: revocation propagates in 'about a minute' and 'cannot be restored.' The irreversibility and propagation latency are exactly the details an agent needs before committing to a destructive call.

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 irreversible effect and capped by the safety instruction. Every clause earns its place 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?

For a destructive, idempotent mutation with no output schema, the description covers the effect, the delay, the irreversibility, and the required human confirmation. Annotations carry the safety profile and the schema carries the parameters, so nothing essential 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?

Schema coverage is 100%, so both account_id and key_id are already documented in the schema (including their api_account provenance). The description adds only an indirect reference to the key's 'name and prefix' as confirmation material, no syntax or format detail beyond the schema. Baseline 3 is warranted.

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 with scope: 'Revoke one of the signed-in person's GolfCore API keys.' The action is unmistakably distinct from api_create_key, but the description never names or contrasts a sibling tool explicitly, so it stops short of full differentiation.

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?

Gives concrete pre-call guidance: 'Confirm the key's name and prefix with the person before calling.' That tells the agent how to invoke responsibly, but there are no explicit when-not conditions or named alternatives for cases where revocation is the wrong choice.

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 only declaring the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description adds substantive behavior: it returns a Stripe checkout URL, it does not charge the user, and for already-paid accounts it diverts to the billing page. Those are exactly the side-effect details an agent needs and none are available in 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?

Three sentences, front-loaded with the action and the destination of the result, with the pricing parentheticals carrying real decision value for the agent. Slightly dense with dollar figures, but nothing is redundant with 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?

For a two-parameter mutation with no output schema, the description covers what is returned (checkout URL), what happens in the alternate account state (billing page), and the required pre-step (ask for the plan). Nothing needed to call 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?

Schema coverage is 50%, and the description compensates by defining the meaning of each plan value, including the monthly price and overage rate, which the bare enum does not convey. The account_id parameter is only covered by the schema's "From api_account" note, so the description does not fully close the coverage gap.

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 ("Start an upgrade of the signed-in person's GolfCore API account") and enumerates the two target tiers with pricing, so the agent knows exactly what the tool does. It does not, however, distinguish itself from the sibling subscribe_premium, leaving a plausible ambiguity about which upgrade path applies to which product.

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 clear operational context — ask which plan the person wants before invoking, and the tool returns a billing page rather than an upgrade when the account is already paid. There is no explicit exclusion or named alternative tool, so it stops 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?

Goes well beyond annotations by enumerating the data the caddie consumes (flag distance, hazards, wind modeled for terrain, elevation, handicap, club distances) and the output shape (a club and a line). It also discloses the first-time sign-in requirement and the Premium gating with its fallback, though it says nothing about latency or failure modes. No contradiction with the 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?

Front-loaded with the purpose and examples, then the required data, then the constraint. It is long but dense with useful detail; the lat/lng instruction duplicates schema text only slightly.

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 6-param tool with no output schema, the description covers inputs, data sources, result shape, auth requirement, and the Premium fallback path. An agent can invoke it correctly without guessing, though error/edge 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 description coverage is 100%, so the schema already documents all six parameters including the lat/lng GPS caveat and the hole/course fallbacks. The description reinforces the lat/lng rule but adds no new syntax or semantics beyond the schema text, which is the expected baseline.

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 action (ask the caddie a question about the shot the golfer is standing over) with concrete examples of the question type (which club, where to aim). Clearly distinct from siblings like distance_to_flag (raw measurement) and subscribe_premium (plan purchase).

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 tells the agent when to pass lat/lng and when to omit them, and forbids asking the golfer for coordinates. It also routes around the Premium gate by naming subscribe_premium as the alternative when the result lists plans.

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 safe-read profile (readOnly, idempotent, non-open-world), but the description adds real behavioral context beyond them: the GolfCore app supplies the position when no args are given, position_age_s reports staleness, hole_inferred signals positional inference, and Premium/sign-in is required. It stops short of describing failure modes or caching beyond staleness.

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?

Purpose and trigger phrases are front-loaded and no sentence is filler, but the description is a dense run-on block mixing return values, argument policy, auth, and inference semantics in one paragraph, making it harder to scan than it needs to be.

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?

There is no output schema, and the description compensates by enumerating the returned fields; it also covers the auth/Premium prerequisite and the positional-inference caveat, leaving nothing essential for a correct call unstated.

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% and each parameter already documents its fallback behavior, so baseline is 3. The description restates the lat/lng policy and the inferred hole/course logic but adds no syntax or format detail the schema lacks; the genuinely new information (position_age_s, Premium gating) concerns behavior rather than parameters.

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+resource (how far the golfer is from the flag) and the user phrasings that trigger it, plus what is returned (course, hole, par, stroke index, yards to pin and green). An agent can separate this from ask_caddie and search without opening a schema.

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?

Explicit when-to-use ('how far is that flag'), explicit argument policy (pass lat/lng only if the device provides GPS, otherwise call with no arguments), and names the alternative path: without Premium the result lists plans for subscribe_premium.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial behavior beyond that: results ordered nearest-first with mileage, per-scope limits, a size warning about scorecards, a citable url on every result, and app_url that opens a course map with no account needed.

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?

Information density is high and there is little filler, but the opening is a single ~120-word run-on sentence packing corpus size, query modes, result fields and flags together. The near/app_url guidance lands late and structure would benefit from breaking out return-shape details.

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 carries the return-value burden and does so thoroughly: per-course fields, scope-dependent scorecard contents, place pages, green figures, url and app_url. For a 6-parameter, zero-required search tool this leaves nothing an agent needs 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 schema already documents near, query, scope, limit, coverage and radius_miles, including the near+query interplay. The description largely restates this (near ordering, empty query with near) without adding new syntax or constraints, 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 (search) and resource (everything GolfCore holds: courses, places, product pages) with concrete query modes (name, local script, architect, slug, place, product). It is unmistakably a search tool, but it never names or differentiates itself from siblings like ask_caddie or distance_to_flag, so the reader must infer the boundary.

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?

Gives real situational guidance: use near with coordinates for 'courses near me'/'near this hotel', leave query empty in that case, and omit 'scorecards' when you only need to know which courses exist because cards are large. No explicit when-not-to-use or named alternative tool, which keeps it below 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?

With annotations only declaring readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, the description carries the real behavioral burden and does so: it discloses the return value (secure Stripe checkout URL plus plan terms), the side-effect boundary (does not charge or activate), pricing, and the first-time-subscriber discount. This is substantially more than the annotations provide.

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 action, the plan menu, and the 'does not charge' caveat are front-loaded, and every sentence carries usable information. The pricing enumeration is somewhat dense for a single description, but it directly supports plan selection rather than padding.

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, single-purpose tool with no output schema, the description covers prerequisites, return shape, and the non-charging guarantee, leaving nothing an agent needs to call it correctly unstated.

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 an enum, so the baseline is 3, but the description earns extra credit by explaining each enum value's price and duration (day_pass $3/24h, plus_monthly $10/mo, plus_yearly $100/yr) and flagging day_pass as the popular on-course choice. That is decision-relevant meaning the schema's terse 'The plan the golfer chose.' does not provide.

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 opening sentence names a specific verb and resource ('Create a GolfCore Premium checkout link') and scopes it to the signed-in golfer, which is entirely distinct from the read-only siblings (ask_caddie, distance_to_flag, search). An agent can identify the tool's function without opening the schema.

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 prerequisite explicitly ('Ask the golfer which plan they want before calling') and clarifies the tool's boundary ('this tool does not charge them or activate Premium'). No alternative subscription tool exists among the siblings, so no when-not guidance is needed, but the agent still has to infer that this is the only path to Premium.

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