Gillby

California swell, wind, tides and buoy observations

get_california_surf

Read-onlyIdempotent

Get an on-demand California surf outlook for a forecastSupported spot ID from list_california_spots. Offshore swell ft/period s/directions FROM, wind kt/FROM, NOAA tide predictions ft MLLW and dated buoy observations. Offshore waves are not breaking-wave heights. Includes an experimental Gillby capped surf preference score (0–100), per-hour factors and model version. Missing essential inputs yield null. This is not a calibrated break-level surf rating; no beach advisory or shark-risk assessment is supplied. Includes parking guidance with checkedAt and official sources (availability null), localGuide where researched, exact NOAA tideEvents ft MLLW, dated NWS regional surf/rip-risk reports for supported Los Angeles spots, detailStatus with separate issues/retrieval time, and planning.days with morning/afternoon ranges in America/Los_Angeles. Null regional/localGuide means unavailable, not safe conditions. locationCameras matches the requested spot and supplies snapshotPath for refreshing JPEG previews, mediaType and unknown capture times; previews are not live video. cameras retains regional camera source links and provider-hosted YouTube IDs where available; these views may differ from the requested break and stream uptime is not guaranteed. Preserve issues and timestamps. sourceStatus distinguishes retrieval, observedAt, issuedAt (null when unknown), forecast validFrom/validThrough, current/stale/unavailable/unknown states, refreshAfterSec and maxObservationAgeSec (Gillby policies, not provider SLAs).

Units: ft, kt, s, F, mi; directions FROM. Returns data and source/freshness metadata.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "get_california_surf"
  }
}

Input Schema

Name	Required	Description	Default
`query`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 19, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Beyond the annotations, it discloses many non-obvious traits: offshore waves are not breaking-wave heights, the score is an experimental 'Gillby' cap (0-100), missing inputs yield null, it is not a calibrated break rating, null localGuide means unavailable rather than safe, camera previews are not live video, and stream uptime is not guaranteed. These caveats materially shape how an agent should interpret outputs.

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

Conciseness3/5

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

The core purpose is front-loaded, but the description is a sprawling block that crams in parking guidance, cameras, YouTube IDs, localGuide and sourceStatus policy details. Much is relevant given no output schema, but the density and single-paragraph structure hurt readability and some clauses could be trimmed.

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

Completeness5/5

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

With no output schema and a nested input object, the description carries the full burden and does so thoroughly, describing return fields (planning.days, detailStatus, sourceStatus, tideEvents), units, freshness metadata, and null semantics. An agent has enough to call and interpret it.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It tells the agent the single 'spot' value must be a forecast-supported ID from list_california_spots, which is more than the raw schema conveys, though it does not restate the regex pattern or length limits.

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

Purpose4/5

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

States a specific verb and resource ('Get an on-demand California surf outlook') scoped to a CA spot ID. It clearly distinguishes itself as a CA-specific, on-demand outlook that bundles swell/wind/tide/buoy data plus a score, but it never explicitly contrasts with the sibling get_surf_forecast, leaving the main sibling ambiguity unresolved.

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

Usage Guidelines4/5

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

Gives a concrete prerequisite: the 'spot' must be a forecast-supported ID obtained from list_california_spots. That routes the agent to the correct source tool. However, there is no explicit when-to-use-this-vs-get_surf_forecast guidance or exclusion, so it falls short of a full 5.

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

All Gillby tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.