Skip to main content
Glama

Supersurf

Find the best surf

find_best_surf
Read-onlyIdempotent

Use this when the person asks where or when to surf around a place. when is in the person's words (tomorrow morning, Saturday, this weekend); default the next 24 hours. Not for one spot's full hours: use get_surf_forecast. Answers surf spots near the place, ranked for the time asked (today, tomorrow, tomorrow morning, this weekend, a date): each spot's best window in that time with its wave height, period, wind and why it ranks there, and the spots with nothing good in that time last; within radius_km (default 30, at most 100).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find_best_surf"
  }
}

Input Schema

NameRequiredDescriptionDefault
latNo
lonNo
nearNoa town, a coast or a spot: Lisbon, Hossegor, Supertubos
whenNoin people's words: today, tomorrow morning, this weekend, Saturday, 2026-11-28
limitNo
radius_kmNo

Output Schema

NameRequiredDescriptionDefault
toYes
fromYes
nearYes
spotsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: ranking order with the weakest results last, the default time window, and the radius cap reducing the search scope. It does not address pagination or result-size limits, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The trigger and the sibling exclusion are front-loaded, and every sentence carries signal. The second sentence is a long run-on packing return values, and since an output schema exists, some of that enumerating (wave height, period, wind) is partly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter, read-only discovery tool with an output schema and full annotations, the description covers the decision-relevant behavior: trigger, default window, ranking semantics and search radius. The remaining gap is how the coordinate parameters relate to the `near` string and what `limit` does, which the output schema cannot compensate for.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33%; the description compensates for `when` (natural-language phrasing, 24-hour default) and `radius_km` (default 30, max 100). However, `lat`, `lon` and `limit` remain unexplained in both the schema and the description, leaving no guidance on choosing coordinates over `near` or on what `limit` caps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete trigger ("when the person asks where or when to surf around a place") and states the output shape: surf spots near a place, ranked for the requested time, each with best window, wave height, period, wind and ranking rationale. It explicitly carves itself apart from get_surf_forecast, which covers one spot's full hours.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when to use it, what the `when` argument means in natural language, the default window (next 24 hours), and the exclusion plus named alternative ("Not for one spot's full hours: use get_surf_forecast"). An agent has an explicit routing rule rather than an inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources