surf-trip-planner

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

Annotations already indicate a read-only operation. The description adds comparison dimensions (ability level, season, etc.) but does not describe output format, response behavior, or data limits. Given the annotations, the description adds moderate context but lacks depth in behavioral disclosure.

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 front-loaded: first sentence states when to use, second sentence lists comparison criteria. Every sentence is relevant, with no unnecessary 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?

Although parameter descriptions are complete and annotations cover safety, the description does not specify the output format or how results are presented. Given that there is no output schema, the description should hint at what the user gets back. The comparison criteria are listed, but completeness is lacking.

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 each parameter already has a description. The tool description does not add new parameter-level details beyond what the schema provides. It gives contextual meaning to the overall comparison, but not to individual 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?

The description clearly states the tool's purpose: comparing specific surf destinations. It specifies the verb 'compare' and the resource 'surf destinations', and the context 'when a user is deciding between specific countries, regions, or surf spots' distinguishes it from sibling tools.

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 when to use this tool ('when a user is deciding between specific...'). While it does not list when not to use, the sibling tool names provide implicit alternatives, making the guidance 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 indicate the tool is read-only and non-destructive. The description only mentions searching guides, adding minimal behavioral context beyond what 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?

A single, front-loaded sentence efficiently communicates the tool's purpose and common use cases without unnecessary text.

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 covers key intents but does not mention the output format or that it returns a list of guides. For a simple tool with no output schema, this is adequate but could be improved.

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 parameters. The description does not add meaningful interpretation beyond the schema, so baseline score 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?

The description clearly states the tool provides surf trip planning guidance and lists specific intents. However, it does not differentiate from sibling tools like recommend_surf_trip_destinations, which could cause confusion.

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 enumerates specific scenarios for using the tool (e.g., landlocked surfer planning, cheap flights). It lacks explicit when-not-to-use guidance or alternative tool references.

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, so the agent knows it's a read operation. The description adds that it fetches a 'live' forecast with a 10-day horizon and 'best days,' providing useful behavioral context beyond 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?

Two sentences with no wasted words. The first sentence fronts the usage case, the second states the action. Very concise 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?

The tool is simple (1 parameter, no output schema). The description fully covers what it does, the type of data returned (forecast and best days), and the scenario in which to use it. 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?

The input schema already has 100% coverage and describes the 'spot' parameter as a name, slug, or ID. The description does not add new parameter details, so baseline score 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 verb 'Fetches' and the resource 'live 10-day Strike Mission forecast and best days for one spot.' It also specifies the use case: when a user asks if a specific spot is worth surfing or traveling to. This distinguishes it from sibling tools that compare spots or find guides.

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 says 'Use this when the user asks whether a specific surf spot is worth surfing or traveling to soon,' providing clear context. It does not mention when not to use it or alternatives, but the instruction is sufficient given 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 provide readOnlyHint and destructiveHint. The description adds disclosure of returned fields (difficulty, hazards, etc.) and Strike Mission links, going beyond annotations. No contradictions.

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 with front-loaded usage guidance. Every sentence is informative with no fluff. Highly efficient and easy to parse.

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 tool with full schema coverage and annotations, the description covers all necessary context: when to use, input format, and output contents. 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?

The only parameter 'spot' has 100% schema coverage. The description adds examples (Uluwatu, uluwatu, 1) and explains the parameter accepts name, slug, or numeric ID, adding value 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 returns planning context for a specific surf spot, including difficulty, hazards, season, travel, wave type, and links. It distinguishes from sibling tools like compare_surf_destinations (comparison) or get_live_spot_forecast (live data).

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 this when the user asks about a specific surf spot.' No explicit when-not, but the sibling tool names imply alternatives for comparisons, guides, and recommendations.

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 no contradiction. The description adds value by detailing return contents (ability fit, season, travel, hazards, dashboard links) and the ranking behavior for near-term trips, which is not implied by 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 a single efficient paragraph with a clear lead sentence and supporting details. It avoids redundancy but could be slightly more compact; still, it earns its 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?

No output schema exists, and the description only partially describes return values (mentions candidates with attributes but not structure). With 10 parameters, some guidance on parameter interactions (e.g., preferredRegions vs preferredCountries) would improve completeness. Adequate but not fully comprehensive.

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 has 100% coverage with descriptions for all 10 parameters. The description does not add additional context or usage hints beyond what is already in the schema, so baseline score 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 returns surf trip destination recommendations with specific attributes (ability fit, season, travel, hazards, dashboard links). It lists several use cases (where to surf, where to fly, plan landlocked trip). However, it does not explicitly differentiate from sibling tools like compare_surf_destinations, which is a minor gap.

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 the tool ('when a user asks where to surf...') and adds nuance about near-term trips and live Strike Scores. However, it does not mention when NOT to use it or suggest alternative sibling tools, leaving some ambiguity.

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