Skip to main content
Glama
savecharlie

io.github.savecharlie/almanac

by savecharlie
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

magnetic_field

Read-onlyIdempotent

Calculate Earth's magnetic field parameters (declination, inclination, intensity) for any location and time using WMM2025 instead of inaccurate recall.

Instructions

Earth's magnetic field from the official World Magnetic Model 2025.

Call this instead of recalling declination or field values from memory: they require a degree-12 spherical-harmonic synthesis and are not reliably predictable token-by-token.

Args: lat: Geodetic latitude in degrees, -90 to 90. lon: Longitude in degrees, -180 to 180. altitude_km: Height above the WGS84 ellipsoid, -1 to 850 km (WMM validity). Defaults to 0 (sea level). when: ISO date/datetime, a bare decimal year (e.g. "2026.5"), or "now". Defaults to "now" (UTC). Must fall in 2025.0–2030.0.

Returns: JSON-serializable dict with: - declination_deg (compass angle off true north, + = east) and compass_note (nearest named point) - inclination_deg, total_intensity_nT, horizontal_intensity_nT and the north/east/down (X/Y/Z) field components in nT - secular_variation: annual rate of change per component - query: echoed inputs and the resolved decimal year - units, model, model_epoch, valid_range, engine, deterministic The payload's own units map documents the unit of every field.

Raises: ValueError: lat/lon/altitude out of range, or a date outside WMM2025 validity [2025.0, 2030.0).

Deterministic and verifiable: a faithful synthesis of NOAA's WMM2025 that reproduces all 100 of NOAA's own published test values to printed precision. Re-run the open-source core to check any answer: github.com/savecharlie/almanac

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
latYes
lonYes
whenNo
altitude_kmNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description builds on this by adding that the tool is deterministic and verifiable, reproducing NOAA's published test values, and that it raises ValueError for out-of-range inputs. It also mentions the underlying engine and a link for verification. These are behavioral details beyond what annotations state.

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

Conciseness5/5

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

The description is well-organized: it starts with the main purpose and usage guidance, then parameter details, return values, error conditions, and determinism. Each sentence adds value, and it is not unnecessarily verbose given the complexity of the tool. The structure is front-loaded with the most critical guidance about why to use this tool.

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?

Given the scientific nature and lack of output schema, the description is exceptionally complete: it covers parameter ranges, defaults, output fields, units, error behavior, and even provides a verification method. An agent has everything needed to call it correctly and interpret results. There are no obvious gaps.

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

Parameters5/5

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

Schema description coverage is 0%, but the description fully explains each parameter: lat and lon with ranges, altitude_km with WGS84 and validity range, and when with formats and default. It also clarifies the return structure, including units and components, so an agent understands exactly what inputs to provide and what to expect.

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 states a clear, specific purpose: computing Earth's magnetic field from WMM2025. It also explicitly differentiates itself from memory-based estimation and from the sibling tool sky_positions by focusing on magnetic field data. The verb 'Call this instead of recalling' adds clarity about its role.

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?

The description explicitly tells the agent when to use this tool: instead of recalling declination or field values from memory, because they require a spherical-harmonic synthesis. It also provides constraints (validity range, coordinate limits) and raises ValueError conditions. It doesn't explicitly mention alternatives beyond the memory-based approach, but it's clear that for magnetic field data this is the tool to use.

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

Deploy Server

Other Tools