Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@astro-cosmic-weather-mcp What's the cosmic weather this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives Claude (and any other MCP-compatible AI agent) live access to a real astronomical ephemeris — moon phases, zodiac transits, void-of-course windows, Mercury retrogrades, solstices/equinoxes, sabbats, natal moon placements, and a flagship combined "cosmic weather" feed.
Real Skyfield + JPL DE440s ephemeris data — not a hallucinated chart. Every number this server returns comes from an actual astronomical calculation or a fixed traditional calendar rule, computed server-side and served over a REST API. Claude never has to guess a moon phase or make up a retrograde date again.
This package is a client only — it makes authenticated HTTPS requests to
the hosted API at https://api.moonrituallibrary.com. It contains no
ephemeris code itself, so it's tiny, has almost no dependencies, and starts
instantly.
Tool | What it answers |
| "What's happening in the sky this week?" — flagship merged feed |
| "What sign is the moon in right now?" |
| "When's the next full moon?" |
| "When does the moon enter Scorpio?" |
| "Is the moon void of course today?" |
| "What was my moon sign?" (given a birth date/time) |
| "When's the next Mercury retrograde?" |
| "When's the next equinox/solstice?" |
| "When is Samhain this year?" |
| Diagnose connection issues |
Related MCP server: Vedaksha
You need an API key before this server can return data (everything except the health check requires one). Two ways to get one:
RapidAPI (pay-as-you-go, credit card, instant): Ephemeris & Cosmic-Weather API on RapidAPI
Direct: request a key at api.moonrituallibrary.com
Free tier is available on both paths — plenty of headroom for personal use inside Claude Desktop.
Pick one:
# Recommended — no separate install step, uvx runs it on demand
uvx astro-cosmic-weather-mcp
# Or install it into your environment
pip install astro-cosmic-weather-mcp
# Or run from source
git clone https://github.com/moonrituallibrary/astro-cosmic-weather-mcp
cd astro-cosmic-weather-mcp
pip install -e .Open your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Add this to the mcpServers block (create the file/block if it doesn't
exist yet), replacing YOUR_API_KEY_HERE with the key from step 1:
{
"mcpServers": {
"astro-cosmic-weather": {
"command": "uvx",
"args": ["astro-cosmic-weather-mcp"],
"env": {
"ASTRO_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}If you installed via pip instead of uvx, use this form instead:
{
"mcpServers": {
"astro-cosmic-weather": {
"command": "astro-mcp",
"env": {
"ASTRO_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Fully restart Claude Desktop (quit, don't just close the window) after editing the config. You should see a small tools/plug icon in the chat box indicating MCP tools are connected — "astro-cosmic-weather" will be listed with its 10 tools.
If you're running your own instance of the underlying API (e.g. self-hosted,
staging), add ASTRO_API_BASE to the same env block:
"env": {
"ASTRO_API_KEY": "YOUR_API_KEY_HERE",
"ASTRO_API_BASE": "https://your-own-host.example.com"
}It defaults to https://api.moonrituallibrary.com if omitted.
Once connected, just ask Claude naturally — it will pick the right tool:
"What's the cosmic weather this week?" Claude calls
cosmic_weatherand gives you a chronological rundown of every moon phase, sign change, retrograde, and sabbat coming up in the next 7 days, plus a headline.
"What sign is the moon in right now?" Claude calls
moon_currentand tells you the live sign, phase, and illumination percentage.
"When is the next Mercury retrograde?" Claude calls
mercury_retrogradesand reports the next upcoming window.
Other things worth asking: "When's the next full moon?", "Is the moon void of course today?", "When is Samhain this year?", "What was my moon sign — I was born March 21, 1994 in Chicago?"
Symptom | Fix |
Tool replies "No ASTRO_API_KEY is configured" | Add/check the |
Tool replies "Authentication failed (401)" | Your key is invalid, expired, or revoked — get a fresh one from the RapidAPI listing or api.moonrituallibrary.com. |
Tool replies "Rate limit or monthly quota exceeded (429)" | You've hit your plan's request cap. Wait for the window to reset or upgrade your plan. |
Tool doesn't show up in Claude Desktop at all | Check |
"Could not connect" / timeout errors | Run the |
This server relays neutral astronomical and traditional-calendar facts only — moon phases, zodiac positions, retrograde windows, solstice/equinox timing, sabbat dates, illumination percentages. It never generates predictions, fortunes, compatibility scores, or claims about future events in a user's life. The underlying API enforces the same rule server-side.
Source layout:
mcp/
├── server.py # the FastMCP server — one tool per API endpoint
├── pyproject.toml # packaging (uvx / pip install)
├── requirements.txt # plain pip deps (mcp, httpx)
├── README.md # this file
└── PUBLISHING.md # registry/discovery listing notesRun locally without installing:
pip install -r requirements.txt
set ASTRO_API_KEY=your_key_here # Windows (cmd)
$env:ASTRO_API_KEY="your_key_here" # Windows (PowerShell)
export ASTRO_API_KEY=your_key_here # macOS/Linux
python server.pyThe server speaks MCP over stdio, so it expects to be driven by an MCP
client (Claude Desktop, the mcp CLI inspector, etc.) rather than run
interactively.
MIT
Check whether the Ephemeris & Cosmic-Weather API is currently reachable and healthy. Use this to diagnose connection problems before assuming a specific data tool is broken — e.g. if another tool call fails with a connection or timeout error, call this first to confirm whether the issue is the service being down versus something else. This endpoint requires no API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that no API key is required and implies a safe, read-only diagnostic operation. It does not explicitly state side effects or response format, but the output schema covers the latter.
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 two sentences, front-loaded with the purpose, and every sentence adds value. It is efficient with no wasted 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?
Given the tool's simplicity (0 params, output schema provided), the description fully covers purpose, usage context, and auth requirements. It leaves no significant gaps for an agent to misuse or misunderstand the tool.
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 has zero parameters, so the baseline is 4. The description adds no parameter-specific detail because none exist; it is appropriately scoped for a parameterless health check.
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 checks whether the Ephemeris & Cosmic-Weather API is reachable and healthy. This distinguishes it from sibling data tools, which focus on specific astronomical/astrological 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?
The description explicitly advises using this tool to diagnose connection problems before assuming a specific data tool is broken, even providing an example (connection/timeout error). This gives clear contextual guidance on when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FLAGSHIP tool: get a single merged, chronological "cosmic weather" feed combining every event type (moon phases, sign ingresses, void-of-course windows, Mercury retrogrades, solar terms, sabbats) for the next N days, plus a human-readable headline summarizing the period. Use this as the default/first tool when the user asks broad questions like "what's the cosmic weather this week?", "what's happening in the sky today?", "give me an astrology overview for the next few days", or anything that isn't obviously scoped to just one event type — it's the richest single call and usually answers the question without needing any other tool.
Args: days: How many days ahead to include, starting from now. Defaults to 7. Use larger values (e.g. 30) for "this month" style questions. tz: IANA timezone name for event timestamps and local-time labeling. Defaults to "UTC".
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC | |
| days | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool returns a merged, chronological feed, includes all event types, and adds a human-readable headline. It also details the 'days' and 'tz' behavior. It does not mention rate limits or error handling, but for a read-only aggregation tool, the behavioral context is sufficiently transparent.
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 well-structured and front-loaded with the 'FLAGSHIP tool' label. It opens with a clear purpose, then provides usage guidance, then parameter details. Each sentence serves a purpose and there is no redundancy. It is longer than minimal but earns its length through rich 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?
Given the complexity of a combined feed covering multiple event types, the description is complete. It covers what the tool does, when to use it, how parameters behave, and the nature of the output (merged chronological feed plus headline). The presence of an output schema means return values need not be spelled out, and the description fills all critical 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?
Schema description coverage is 0%, so the description compensates fully. It explains 'days': 'How many days ahead to include, starting from now. Defaults to 7. Use larger values (e.g. 30) for "this month" style questions.' It explains 'tz': 'IANA timezone name for event timestamps and local-time labeling. Defaults to "UTC".' This adds meaningful semantics beyond the raw 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's purpose: 'get a single merged, chronological cosmic weather feed combining every event type.' It uses a specific verb (get), a specific resource (cosmic weather feed), and distinguishes itself from sibling tools by being the default/first tool for broad questions. It explicitly contrasts with tools scoped to one event type.
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 provides explicit guidance on when to use this tool: 'Use this as the default/first tool when the user asks broad questions...' It gives concrete examples and states that it is the 'richest single call' and 'usually answers the question without needing any other tool.' It implies when not to use it (when the query is scoped to one event type), effectively covering alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Mercury retrograde windows (paired start/end dates) within a date range. Use this when the user asks "when is the next Mercury retrograde?", "is Mercury retrograde right now?", or wants a schedule of upcoming retrograde periods. If no range is given, the API defaults to now through +90 days — for "is it retrograde right now" pass a range that starts before today.
Args: from_date: Start of the range, ISO 8601 (e.g. "2026-01-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-12-31"). Omit for "90 days from the start".
| Name | Required | Description | Default |
|---|---|---|---|
| to_date | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It does a good job by explaining default date ranges ('now through +90 days'), the paired nature of the results, and the need to start the range before today for current retrograde checks. It does not describe exact output structure, but the output schema covers that.
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 well-structured: purpose first, then usage guidance, then argument details. Every sentence provides useful information, and there is no repetition or fluff.
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 tool with two optional parameters, clear defaults, and an output schema, the description is complete. It covers invocation scenarios, parameter semantics, and behavioral nuances, so the agent can select and call it correctly without additional context.
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 schema only provides parameter names and types, with zero description coverage. The tool description compensates fully by explaining each parameter's meaning, format, and default behavior, including examples and guidance on omission.
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 'List Mercury retrograde windows (paired start/end dates) within a date range,' which names a specific action, resource, and scope. It distinguishes itself from sibling tools by focusing on Mercury retrograde periods rather than moon-related phenomena.
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 lists example user queries that should trigger this tool and explains how to handle the 'right now' case. It does not explicitly state when not to use it or name alternative tools, but the use cases are clear and cover the main scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Moon's CURRENT (right-now) position and phase: zodiac sign, ecliptic longitude, phase name (e.g. "Waxing Gibbous"), and illumination percentage. Use this when the user asks "what sign is the moon in right now?", "what phase is the moon in today?", or "how full is the moon tonight?" — anything about the present moment, not a future/past date.
Args: tz: IANA timezone name for any timestamps in the response (e.g. "America/New_York", "Europe/London"). Defaults to "UTC".
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clarifies the 'current' nature and the timezone handling, but it does not mention potential edge cases (e.g., invalid timezone), side effects, or affirm read-only safety. The description is adequate but not rich in behavioral context.
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 efficiently structured with a clear purpose sentence, usage examples, and a labeled Args section. Every sentence adds value; there is no filler or repetition.
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?
Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description provides sufficient contextual coverage. It explains what the tool returns, when to use it, and the one parameter's meaning, leaving no critical 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 schema only provides the parameter name, type, and default value. The description adds a detailed explanation of tz, including its purpose for timestamps, concrete timezone examples, and the default 'UTC'. This fully compensates for the 0% schema description coverage.
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 opens with a specific verb and resource: 'Get the Moon's CURRENT (right-now) position and phase', and enumerates the exact data fields (zodiac sign, ecliptic longitude, phase name, illumination percentage). It clearly distinguishes from sibling tools by emphasizing 'right-now' and contrasting with future/past dates.
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 with sample user queries and adds the exclusion 'not a future/past date'. However, it does not name a specific alternative tool, so it lacks the full 'alternatives' component required for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List New Moon / First Quarter / Full Moon / Last Quarter events within a date range. Use this when the user asks "when is the next full moon?", "list the moon phases this month", or "when was the last new moon?". If no range is given, the API defaults to now through +90 days.
Args: from_date: Start of the range, ISO 8601 (e.g. "2026-08-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-11-01"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps and any local-time labeling. Defaults to "UTC".
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC | |
| to_date | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the default date range (now through +90 days) and clarifies timezone handling (IANA timezone for returned timestamps and local-time labeling). This is meaningful behavioral context, though it does not mention auth/rate limits or sorting behavior.
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 tightly structured: purpose statement, usage examples, default behavior, then parameter breakdown. Every sentence adds value, with no fluff or repetition. Front-loaded with the core function.
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?
Given the presence of an output schema (which handles return field details), the description sufficiently covers the main behavioral aspects: what is returned (four phase types), date range semantics, default behavior, and timezone handling. The examples ensure the agent can select this tool appropriately among numerous siblings.
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 schema has 0% description coverage, but the description fully compensates. Each parameter (from_date, to_date, tz) is explained with ISO 8601 examples, defaults, and semantic meaning (e.g., 'Omit for starting now'). This exceeds the baseline and leaves no ambiguity.
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 opens with a specific verb 'List' and explicitly names the four moon phase events (New Moon / First Quarter / Full Moon / Last Quarter) within a date range. This clearly distinguishes from siblings like moon_current (which returns the current phase) and moon_void_of_course.
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?
Provides explicit when-to-use guidance with concrete example queries ('when is the next full moon?', 'list the moon phases this month'). Does not explicitly state when not to use or name alternative sibling tools, but the examples effectively communicate the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Moon zodiac sign ingress events (the exact moments the Moon moves from one zodiac sign into the next) within a date range. Use this when the user asks "when does the moon enter Scorpio?", "what sign is the moon moving into next?", or wants a schedule of moon-sign changes. If no range is given, the API defaults to now through +90 days.
Args: from_date: Start of the range, ISO 8601 (e.g. "2026-08-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-11-01"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps. Defaults to "UTC".
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC | |
| to_date | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and discloses important behaviors: defaults to now through +90 days, ISO 8601 date formats, and timezone handling. It does not mention error conditions or rate limits, but the presence of an output schema reduces the need to describe return values, and the disclosed defaults are valuable behavioral context.
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 front-loaded with the core purpose in the first sentence, followed by usage examples and defaults. The Args section is clearly structured and concise. Every sentence adds necessary information without 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?
The tool is moderately complex with three optional parameters, an output schema, and several sibling tools. The description covers what the tool does, when to use it, parameter semantics, and default behaviors. The output schema handles return-value documentation, so nothing critical 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 description coverage is 0% (the schema itself has no property descriptions), but the tool description fully compensates with an Args section. It explains each parameter's meaning, format (ISO 8601), examples, omit behavior, and timezone default. This adds significant value beyond the bare schema types.
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 uses a specific verb ('List') and resource ('Moon zodiac sign ingress events'), defines exactly what constitutes an ingress (the moment the Moon moves from one sign into the next), and provides example user queries. This clearly distinguishes it from sibling tools like moon_phases and moon_void_of_course.
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 'Use this when...' and gives concrete user-phrase examples, making the primary use case clear. It also explains default date-range behavior. However, it does not explicitly mention alternatives or say when not to use this tool, though the specificity inherently differentiates it from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Void-of-Course Moon windows (periods between the Moon's last major aspect in a sign and its ingress into the next sign) within a date range. Use this when the user asks "when is the moon void of course this week?" or "is the moon VOC right now?". If no range is given, the API defaults to now through +90 days.
Args: from_date: Start of the range, ISO 8601 (e.g. "2026-08-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-11-01"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps. Defaults to "UTC".
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC | |
| to_date | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses default range behavior (now through +90 days), optional parameter omission semantics, and timezone defaults. It does not discuss rate limits or output format, but the output schema covers the latter.
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 well-structured: purpose first, then usage examples, then defaults, then an Args section with each parameter clearly described. Every sentence adds value with no fluff.
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 simple read-only list tool with 3 optional parameters, the description covers purpose, usage, parameter semantics, defaults, and timezone handling. The output schema exists, so return values need not be repeated. This is complete.
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 0%, but the description compensates fully by explaining each parameter: start/end of range, ISO 8601 format, defaults, and what omission means. This goes well beyond the schemas' bare property names.
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 uses a specific verb 'List' and resource 'Void-of-Course Moon windows', defines the concept, and scopes it to a date range. This clearly distinguishes it from sibling tools like moon_phases or moon_current.
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 explicitly states 'Use this when the user asks...' with concrete example queries, providing strong when-to-use guidance. However, it does not mention when not to use or name alternatives, so it misses the full 5 criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the natal (birth) Moon placement for a specific birth date and time: Moon zodiac sign, Moon phase at that moment, and illumination percentage. Use this when the user asks "what was my moon sign?" or gives a specific birth date/time and wants their Moon placement. If the user only knows their birth date and not the exact time, use the default "12:00" and tell them the sign may be inexact if the Moon changed signs that day.
Args: date: Birth date, ISO 8601 (e.g. "1994-03-21"). Required. time: Birth time in 24-hour HH:MM format (e.g. "14:30"). Defaults to "12:00" (noon) if unknown. tz: IANA timezone name for the birth location at the time of birth (e.g. "America/Chicago"). Defaults to "UTC" — for an accurate result this should be the timezone that was in effect at the birth location and date, not the user's current timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC | |
| date | Yes | ||
| time | No | 12:00 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well: it discloses default time (12:00), default timezone (UTC), warns that sign may be inexact if Moon changes signs, and emphasizes timezone must be the birth location's then-effective zone. This goes beyond basic operation.
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 serves a purpose: main action, usage trigger, fallback behavior, and parameter specifications. The Args section is cleanly structured without 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?
Output schema exists, so return values need not be explained. Input handling, defaults, and edge cases (unknown time, wrong timezone) are all covered. This is complete for a computational astrology tool.
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 0%, but the description explains each parameter in detail: date format (ISO 8601), time format (24-hour HH:MM) plus default, tz format (IANA) plus default and correctness caveat. Fully compensates for the schema's lack of descriptions.
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?
Description uses a specific verb+resource: 'Compute the natal (birth) Moon placement' and lists concrete outputs (zodiac sign, phase, illumination). It clearly distinguishes from siblings like 'moon_current' by tying to birth date/time context.
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 usage trigger is given: 'Use this when the user asks "what was my moon sign?" or gives a specific birth date/time...'. It also provides guidance for missing time and timezone caveats, though it doesn't explicitly name alternative tools for when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Wheel of the Year sabbats (Samhain, Yule, Imbolc, Ostara, Beltane, Litha, Lughnasadh, Mabon) with their dates for a given year and hemisphere. Use this when the user asks "when is Samhain this year?", "list the sabbats for 2026", or asks about the pagan/wiccan wheel of the year. Southern hemisphere sabbat dates are offset by ~6 months from northern hemisphere ones (the seasonal correspondence flips).
Args: year: Calendar year (e.g. 2026). Omit to use the current year. hemisphere: Either "north" or "south". Defaults to "north".
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| hemisphere | No | north |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that southern hemisphere dates are offset by ~6 months and that hemisphere defaults to 'north', which are key behavioral traits. It doesn't explicitly mention read-only status but that is implied for a listing tool.
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 tightly written: purpose first, then usage examples, then behavioral note, then parameter definitions. Every sentence adds value, no redundancy or fluff.
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?
Comprehensive for a simple two-param listing tool. Covers purpose, usage, hemisphere behavior, parameters, and output schema is present. No significant 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 has no descriptions (0% coverage), but the description fully explains both parameters: year (optional, current year if omitted) and hemisphere (north/south, with default and reason for offset). This goes well 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 lists Wheel of the Year sabbats with specific dates for a given year and hemisphere. It provides the exact sabbat names and examples of user queries, distinguishing it from sibling tools like moon_phases or solar_terms.
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 guidance is given via example queries and reference to the pagan/wiccan wheel of the year. However, no alternatives or when-not-to-use exclusions are stated, though sibling names make the scope fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List solstices, equinoxes, and cross-quarter days (the astronomical solar-year turning points) within a date range. Use this when the user asks "when is the next equinox?", "when does summer solstice happen this year?", or wants the solar calendar. If no range is given, the API defaults to now through +90 days.
Args: from_date: Start of the range, ISO 8601 (e.g. "2026-01-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-12-31"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps. Defaults to "UTC".
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | UTC | |
| to_date | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that the tool lists events (read-only), defaults to now through +90 days, and returns timestamps localized to an IANA timezone. It doesn't mention pagination, rate limits, or authentication, but for a simple read-only list tool this is adequate.
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 front-loaded with the core purpose and usage trigger, followed by a concise Args block. Every sentence adds value, and the format is easy to scan for an agent.
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 tool with 3 params, an output schema, no required params, and clear defaults, this description is nearly complete. It could briefly contrast with the 'sabbats' tool to prevent confusion, but the core information needed for correct selection and invocation is present.
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 0%, so the description must fully compensate. It explains each parameter (from_date, to_date, tz) with examples, defaults, and important semantic details like 'Omit for starting now' and 'Omit for 90 days from the start.' This is exemplary parameter documentation.
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 uses a specific verb ('List') and identifies the exact resources: solstices, equinoxes, and cross-quarter days. This clearly distinguishes it from sibling tools like moon_phases and sabbats, which cover different astronomical/calendar events.
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 provides explicit 'Use this when' guidance with concrete user queries ('when is the next equinox?') and describes the default behavior when no range is supplied. It does not explicitly mention when not to use it or suggest alternative tools, but the guidance is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0api_healthcosmic_weathermercury_retrogradesmoon_currentmoon_phasesmoon_sign_ingressesmoon_void_of_coursenatal_moonsabbatssolar_termsScored across 10 tools
Each tool has a clearly distinct purpose: current moon state, phase events, sign ingress events, void-of-course windows, natal computation, Mercury retrogrades, solar terms, sabbats, a merged feed, and health check. The flagship cosmic_weather tool is explicitly presented as an aggregation, reducing overlap.
Tool names use a consistent lowercase snake_case style with descriptive noun phrases (moon_phases, solar_terms, sabbats). Minor inconsistency: natal_moon breaks the moon_ prefix pattern used by other moon tools, and there is no verb_noun pattern, but the naming is still predictable.
10 tools is well-scoped for an astro-cosmic weather server, covering the moon, Mercury, solar terms, sabbats, and a combined feed. Each tool adds distinct value without redundancy.
The set covers current and natal moon states, future/past event lists, windows, retrogrades, solar terms, and sabbats, plus a health check. Gaps include lack of other planetary retrograde tools and no direct 'moon at date' tool, but inferring from ingresses is possible.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
