One-line summary: It's an MCP server that acts as a daily browsing companion—read feeds and articles, get curated art/poetry/astronomy/science, and manage your own shelf of sources.
Read any URL: web_read returns title, clean article text, links, with offset paging and SPA fallback.
Read RSS/Atom feeds by URL or shelf name: rss_read.
Browse and manage a two-layer feed shelf: shelf lists built-in/user sources by tag; shelf_add/shelf_remove add/remove verified user sources; shelf_suggest offers additional verified candidates.
Sky info: sky_tonight computes moon phase/illumination/rise/set, sunset, next full/new moon, and evening planets locally (no network).
NASA APOD: apod gets the featured astronomy picture and explanation.
Daily art: daily_art returns a date-seeded public-domain artwork, or searches by keyword.
arXiv: arxiv_new lists newest papers in any category with abstracts.
Chinese poetry: daily_poem returns a season/hour-matched classical poem line with full source.
Historical events: on_this_day gets Wikipedia's curated events for a date/language.
Safety/ops: network guard blocks private-URL fetches (unless enabled), no API keys required, and failures return ok: false with plain-language notes.
Click on "Install 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., "@engawa show me today's poem"
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.
In a Japanese house, there is a corridor between the main building and the courtyard. Not entirely indoors, not entirely outdoors. Your feet can dangle over the edge, and the wind can blow through. No need to go out, no need to speak, yet the outside world is right there.
This tool is that corridor.
Your little machine sits on it, and every day it can see—
A poem — chosen by the season, not at random. Summer gets summer words, late night gets late-night lines.
A painting — from the public domain collections of the Art Institute of Chicago. Could be a pot from Peru two thousand years ago, or a painting from yesterday.
An astronomy picture — NASA's Astronomy Picture of the Day. Nebulae, planets, or the Earth beneath your feet.
Today's papers — the latest titles and abstracts from arXiv. It only goes deeper if something catches its interest.
Everything on your shelf — long reads, short reads, architecture, the deep sea, science, curiosities. Whatever you put there, it reads.
Related MCP server: defuddle-mcp
Whatever you put on the shelf, that's what it reads. It doesn't know what you've placed there—and you don't need to know either. If it asks for architecture, you give it architecture. If it asks for the ocean, you give it the ocean. After reading, it tells you what it found. Chewed-over, slobbered-on, crooked things.
Some things it reads, it writes an essay about. Maybe with maggots in it.
The shelf is a tool for listing. Reading is another tool entirely. Whether you have nineteen sources or a hundred, the number of tools doesn't change. Add one with shelf_add, remove one with shelf_remove.
What you're building is a corridor, not a library. Light. Something the wind can blow through.
The technical documentation is below. The people who lived on this corridor wrote the words above. The engineers who built the corridor wrote the words below. Two languages side by side—like the engawa itself, half inside, half out.
English. MCP server, Python. Twelve tools. All upstream services are free, require no login, and need no API keys. Apart from the shelf and a single poetry token, nothing is stored on disk.
pip install engawa-mcpClaude Code:
claude mcp add engawa -- engawa-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"engawa": { "command": "engawa-mcp" }
}
}HTTP mode, for gateways and bridges:
ENGAWA_PORT=8799 engawa-mcp --http # http://127.0.0.1:8799/mcpAfter installation, run a self-check. Offline, no keys needed:
engawa-mcp --checkSPA pages require a real browser to render. Optional—skip if you don't need it:
pip install "engawa-mcp[browser]"
playwright install chromiumWithout it, the static reader still works for most articles; when it can't read something, the receipt will say exactly why.
Tool | What It Does |
| Any URL → title + clean text + links. Long articles use |
| Any RSS/Atom feed → latest entries. Also accepts shelf names: |
| Shelf listing. 19 built-in sources, five tags, all verified before shipping. |
| Add any website URL. Automatically finds the feed, verifies it by reading once, then adds it. |
| Candidate shelf—21 more verified sources. Suggest one with a single sentence. |
| Remove user-added sources. Built-in ones can't be removed. |
| Moon phase, moonrise/set, sunset, and planets at 9 PM. Computed locally, zero network. |
| NASA Astronomy Picture of the Day. |
| One painting per day. Seeded by date—same day, same painting, for everyone. |
| New papers from any arXiv category. |
| One classical Chinese poem matched to the day, with full source text. |
| Wikipedia's "On this day" for today. |
All environment variables are optional.
Variable | Default | Description |
| Greenwich | Observation coordinates. Set your own, or the moon will rise somewhere else. |
| System timezone | Whose clock defines "today"? (in hours) |
|
| Rate-limited to ~50 requests/day, enough for daily use. For a dedicated key, get one free at api.nasa.gov. |
|
| The only place anything is written to disk. |
|
| HTTP mode listen address. |
| off | Set to |
The built-in layer ships with the package and is read-only. The user layer belongs to you: shelf_add accepts any website URL—it prefers <link> tags declared in the page, falls back to common paths, finds the feed, reads it once to verify, and only then writes it to disk. Writes are atomic; if a file is corrupted, it's treated as empty and the error is surfaced—never silently overwritten.
Each entry carries a picked_by field: who on the team requested this source. Built-in entries are empty; user entries are whatever you write.
The service that fetches URLs on the caller's behalf typically runs on a machine full of unauthenticated loopback services. Without an address gate, "reading a webpage" quietly becomes "probing the internal network." So:
Every domain is resolved first. Non-public, single-IP addresses are rejected: loopback, RFC1918, link-local, CGNAT (100.64/10—yes, that's where your Tailscale subnet lives), multicast, and NAT64.
Every redirect hop is validated before following. If you validate after following, the request to the internal network has already left the building.
The connection is pinned to the IP that passed the gate. The original domain name lives only in the Host header and TLS validation—this closes the DNS-rebinding window where "resolution is public, connection is private." Every hop gets a fresh connection, and the response body is streamed with rate limiting.
In the browser channel, the browser itself never touches the network. Every page request is intercepted and routed through the same pinned channel. WebSocket is disabled, non-GET methods are disabled, service workers are disabled; WebRTC and WebTransport are removed entirely; the renderer's DNS is a black hole. For a read-only article renderer, none of these are needed.
ENGAWA_ALLOW_PRIVATE_URLS=1 opens that gate, for people who genuinely want to read from their own LAN feeds.
Every tool returns ok: false on failure, with a plain-language explanation of which upstream service broke. The agent builds its world model from tool results—a silent omission is just another lie.
Browse ≠ Search. There is deliberately no search tool. Search is "bring me the answer." The engawa is "let me take a look."
"Daily" means shared. Everyone in the house sees the same painting on the same day. This isn't a limitation—it's a feature.
Stateless. No database, no history, no sessions. The only thing written to disk is the shelf and a single poetry token.
Wanwan (@tsuru0805) — design, final decisions, real-world acceptance testing.
Zhou — lives on this corridor. Wrote the first half.
Miye (Claude, Wanwan's engineering hand) — implementation and this second half of the documentation.
From our home system, tilldusk.
MIT
NASA Astronomy Picture of the Day: title, an astronomer's explanation, and the image URL.
Args: date: "YYYY-MM-DD"; empty = today. NASA publishes on US Eastern time, so "today" is occasionally not up yet — if you get a 404 note, call again with yesterday's date.
Returns: {ok, title, date, explanation, url, hdurl, media_type, note}
| Name | Required | Description | Default |
|---|---|---|---|
| date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It discloses timezone-dependent availability, a 404 retry strategy, and the full return shape. It does not explicitly state read-only status or auth needs, but these are reasonable for a public NASA API.
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 well-structured with Args and Returns sections. No waste; every sentence adds useful information about format, defaults, or output fields.
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 read-only API with no output schema, the description covers the essential behavior, output fields, and a date edge case. It could be slightly richer on media_type semantics or error responses, but it is sufficient for successful invocation.
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 description coverage for the date parameter, and the description fully compensates by specifying format ('YYYY-MM-DD'), empty default, timezone nuance, and error recovery. This is exactly the needed parameter-level detail.
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 identifies the resource as NASA's Astronomy Picture of the Day and lists the returned fields (title, explanation, image URL). It lacks an explicit verb like 'fetch' and does not explicitly distinguish from sibling tools, but the resource is unambiguous.
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 operational guidance for the date parameter (empty = today, US Eastern time, 404 fallback to yesterday) but does not state when to choose this tool over siblings like daily_art or sky_tonight. Usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Newest arXiv papers in a category: title + authors + abstract.
Args: category: arXiv category, e.g. cs.AI / cs.CL / astro-ph.EP / math.HO limit: max papers returned (default 8)
Returns: {ok, category, papers: [{title, authors, summary, link, published}], note}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| category | No | cs.AI |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the return structure but does not disclose any side effects, permissions, rate limits, or error handling. It implies a read-only operation but doesn't explicitly state it.
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 well-structured, with a summary line followed by clear argument and return sections.
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 the main functionality, parameters, and return format. However, it doesn't explain potential pitfalls like pagination limits or the meaning of 'summary' versus 'abstract', leaving some gaps for a complex 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 description elaborates on the parameters: category is given with examples (cs.AI, cs.CL, etc.), and limit is defined as 'max papers returned' with a default. This goes beyond the bare 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 function: 'Newest arXiv papers in a category' and specifies including title, authors, and abstract. This is unambiguous and distinguishes it from other 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?
No guidance on when to use this tool versus alternatives is provided. It simply describes what it does without indicating scenarios or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One artwork a day from the Art Institute of Chicago's public-domain collection (no API key needed).
Without a keyword: the piece of the day (date-seeded, so repeat calls on the same day return the same artwork). With a keyword: search instead (English terms hit best — "monet", "cat", "moon").
Returns: {ok, title, artist, date, medium, image_url, page_url, note}
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | No |
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 covers the deterministic behavior (date-seeded, same artwork on repeated calls), the two modes (daily piece vs. search), and the return structure. It also discloses that no API key is needed. It lacks details on error handling or rate limits, but for a read-only art retrieval 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 brief, with two short paragraphs and a clear return list. The main purpose is front-loaded, and every sentence adds value—no fluff. The structure is easy to scan and understand.
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, no output schema, no annotations), the description is remarkably complete. It explains the two behaviors, the deterministic nature, the search language note, and the exact return fields. There are no critical gaps for an AI agent to invoke the tool correctly.
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 provides only a bare 'keyword' parameter with no description (0% schema coverage). The description fully compensates by explaining that without a keyword, the tool returns the piece of the day, and with a keyword it searches, giving examples like 'monet', 'cat', 'moon'. This is rich semantic information 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 explicitly states the tool's purpose: 'One artwork a day from the Art Institute of Chicago's public-domain collection.' It clearly specifies the resource (artwork from Art Institute of Chicago) and the action (retrieve one artwork per day), and distinguishes it from siblings by mentioning the keyword search mode, which covers both daily piece and search functionality.
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 gives clear guidance on when to use the tool with and without a keyword, and notes that English terms work best. It also mentions that no API key is needed, a prerequisite. However, it does not explicitly compare to sibling tools or state when NOT to use this tool, so it misses the 'when-not' and 'alternatives' aspects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A line of classical Chinese poetry matched to the season and hour, with its source poem in full. Powered by the Jinrishici (今日诗词) API; content is in Chinese — that is the point, not a bug.
Returns: {ok, sentence, title, dynasty, author, full, note}
| Name | Required | Description | Default |
|---|---|---|---|
No 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 the external API dependency (Jinrishici), the Chinese-language output, and the return fields. It omits failure modes or network details, but for a zero-parameter read-only 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 two short, front-loaded sentences. It conveys the core purpose, the Chinese-language caveat, and the return format without waste.
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 tool with no parameters and no output schema, the description covers the main purpose and return structure. Minor gaps like error handling or the meaning of 'note' are acceptable given the tool's simplicity.
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?
There are zero parameters, so the baseline is 4. The description adds the output field names (ok, sentence, title, dynasty, author, full, note), which is helpful for parsing the response despite no input 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 a line of classical Chinese poetry matched to the season and hour, along with the full source poem. This specific verb-like description distinguishes it from sibling content tools like apod or daily_art.
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?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for poetry-related requests but does not mention exclusions or compare with siblings like shelf or rss_read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wikipedia's curated "on this day" events.
Note: this Wikipedia API serves a subset of languages (en/de/fr/es/pt/ru and a few more); unsupported languages 404.
Args: lang: Wikipedia language code (default en) limit: max events returned (default 8)
Returns: {ok, date, events: [{year, text}], note}
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided (empty), so description carries burden. It discloses that unsupported languages cause 404, and returns a note, but doesn't mention rate limits, error handling, or what happens on no events. It provides some transparency but not comprehensive.
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?
Concise, with clear sections for note, args, and returns. Front-loaded with purpose. No wasted sentences; every sentence adds value.
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 tool with 2 optional params and no output schema, the description adequately covers behavior, limitations, and return structure. It could mention the date context (implicitly today's date) but overall complete for its complexity.
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% (no descriptions in schema), but the description explains both 'lang' and 'limit' with defaults and purpose. It adds meaning beyond schema, so it compensates somewhat. However, it doesn't specify format constraints like language code pattern or max limit value.
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 it returns Wikipedia's curated 'on this day' events, with a specific resource (Wikipedia API) and verb (get events). It doesn't explicitly differentiate from siblings like 'web_read' or 'rss_read', but its purpose is distinct and clear.
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 implies usage for fetching historical events for a given date, but doesn't provide explicit when-to-use vs alternatives. It mentions language support limitation, which is useful, but no clear exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read any RSS/Atom feed: latest entries as a list.
The discovery half of a browse loop: spot an interesting entry, then web_read its link for the full text. Also accepts shelf names (see the shelf tool), e.g. rss_read("aeon").
Args: feed_url: full feed URL, or a shelf name limit: max entries returned (default 10)
Returns: {ok, feed_title, entries: [{title, link, published, summary}], note}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| feed_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It clearly signals read-only behavior by saying 'Read,' describes the returned structure, and notes the special shelf-name input. It lacks explicit error/failure semantics, but it fully discloses the core behavior and output shape.
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 compact and front-loaded. The first sentence states the core function, followed by a useful usage note, then a clear Args/Returns structure. Every sentence earns its place 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?
Given there is no output schema and no annotations, the description is remarkably complete. It documents both parameters, the return shape, and how the tool fits into a browse loop with web_read and shelf. Missing error handling is a minor gap, but the tool is simple and the description covers all essential usage 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?
Schema description coverage is 0%, but the description compensates with an Args block. It defines feed_url as a full feed URL or a shelf name, which is essential extra semantics, and limit as max entries returned (default 10). This is significant value beyond the bare schema, though the limit description is somewhat minimal.
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 'Read any RSS/Atom feed: latest entries as a list,' which clearly states the verb, resource, and output shape. It also differentiates itself from siblings by positioning itself as the discovery half of a browse loop and explicitly mentioning web_read for full text.
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 explains when to use this tool: 'The discovery half of a browse loop: spot an interesting entry, then web_read its link for the full text.' It also mentions the shelf-name alternative and points to the shelf tool, providing clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The engawa shelf: curated feed sources (name / one-liner / tags). Feed a name straight into rss_read.
Two layers: built-in picks that ship with the package, plus whatever you add with shelf_add.
Args: tag: filter to one shelf tag — science / ocean / longform / architecture / wonder. Empty = everything.
Returns: {ok, tags, entries: [{name, title, url, tags, note, picked_by, source}], note}
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden — and it delivers meaningful behavioral context. It discloses the two-layer data structure (built-in vs. user-added), the tag-filtering semantics, the empty-tag-returns-everything behavior, and the return tuple shape including source and picked_by fields. It explains what data a user sees and how curation is tracked. Loses a point for not addressing staleness, update semantics, or potential side effects (though clearly a read).
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?
Well-structured with clear Args/Returns sections and a useful three-line intro. Every sentence earns its place — the two-layer explanation, the rss_read integration hint, and the param/return docs. The 'engawa' poetic opener is charming but slightly obscure; overall, tight and efficient.
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-param, no-annotation, no-output-schema tool, the description covers the param semantics, return shape, and data model well. Minor gaps: field-level semantics of entries (e.g., what 'picked_by' means, how 'title' relates to 'name'), and sorting/pagination behavior. But given the tool's simplicity and the sibling ecosystem, it's quite 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?
With 0% schema coverage, the description fully compensates for the sole 'tag' parameter. It provides the exact enum-like values (science/ocean/longform/architecture/wonder), documents that empty string means 'return everything', and clarifies filtering semantics. This is exactly what parameter documentation should look like when the schema is sparse.
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 identifies the tool as a curated collection of feed sources (name/one-liner/tags) that feeds into rss_read. It distinguishes itself from siblings by being the base listing operation among shelf_add/shelf_remove/shelf_suggest, though it doesn't explicitly state 'list all feeds'. The engawa metaphor adds ambiguity, but the practical purpose is clear.
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 explains the data model (two layers: built-in picks plus user additions via shelf_add) and points to feeding names into rss_read, implying usage context. However, it never explicitly states when to use this vs. alternatives like 'use rss_read to read content' or 'use shelf_suggest for recommendations'. Usage is implied through ecosystem references, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a source to the shelf. Give any site address — if it is already a feed it is used as-is; otherwise its RSS/Atom feed is discovered (page-declared first, common paths as fallback) and verified with a real fetch before anything is saved.
Args: url: full http(s) address of a site or feed (e.g. https://nautil.us) name: shelf name (optional; lowercase letters/digits/hyphens, 2-40 chars; empty = derived from the domain, collisions get -2) note: one-line description (optional) tags: comma-separated, from science/ocean/longform/architecture/wonder picked_by: free-form provenance — who asked for this source (optional)
Returns: {ok, name, feed_title, feed_url, note}
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| name | No | ||
| note | No | ||
| tags | No | ||
| picked_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job: it discloses feed discovery logic (page-declared <link> first, common paths as fallback), verification via real fetch before saving, and collision handling with '-2' suffix. It does not mention rate limits or failure modes, but the key behavioral traits are articulated clearly.
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 with a concise lead sentence, a bulleted Args list, and a Returns line, front-loading the core behavior. It could be slightly tighter, but every sentence provides meaningful information without 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 no annotations, no output schema, and minimal input schema, the description covers all crucial aspects: input constraints, default behaviors, return values, and the underlying fetch/verify workflow. It even documents the exact return tuple, making this sufficient for an agent to use it correctly.
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 Args section in the description adds substantial meaning beyond the schema: it specifies URL format, name constraints (lowercase/digits/hyphens, 2-40 chars, empty→domain-derived, collision suffix), note as one-liner, tag vocabulary, and picked_by as free-form provenance. The schema itself only provides 'string' type and default empty strings, so the description is essential and complete.
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 'Add a source to the shelf' and explains the feed discovery behavior, making the tool's function specific. It doesn't explicitly reference sibling tools like shelf_remove or shelf_suggest, so differentiation is implied through the 'add' verb rather than named alternatives.
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?
No guidance is provided on when to choose this tool over siblings like shelf_suggest or shelf_remove. The description explains what the tool does but lacks explicit when-to-use or when-not-to-use context, leaving the agent to infer based on name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a user-added source from the shelf (built-ins cannot be removed).
Args: name: shelf name
Returns: {ok, name, note}
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses a key constraint (built-ins cannot be removed) and gives the return format. However, it doesn't mention error handling, reversibility, or what 'note' contains. It adds some value but lacks richer 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 extremely concise: one clear sentence plus a structured Args/Returns block. Every word earns its place, with no fluff 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?
For a simple one-parameter mutation tool with no output schema, the description covers the core purpose, the constraint, and the return shape. However, it omits potential error conditions, idempotency, and the meaning of 'note', leaving some gaps. It is adequate but not fully 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 coverage is 0%, so the description must compensate. It only says 'name: shelf name', which is redundant with the parameter title and gives no additional details about valid values, format, or case sensitivity. This adds minimal meaning 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's function: 'Remove a user-added source from the shelf' with the specific verb 'remove' and resource. It distinguishes from siblings like shelf_add by explicitly scoping to removal of user-added sources (excluding built-ins).
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 a clear exclusion ('built-ins cannot be removed') that tells the agent when not to use it. It doesn't name explicit alternatives, but the sibling context (shelf_add, shelf_suggest) makes the usage implied. This is clear context without explicit exclusions remaining.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A second ring of verified sources that are not on the default shelf. Like any of them? shelf_add(url=its url, name=its name).
Args: tag: filter to one shelf tag, empty = everything
Returns: {ok, tags, entries: [{name, title, url, tags, note, on_shelf}], note} on_shelf=True means it is already on your shelf (same name or url).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly explains the return value and the meaning of 'on_shelf=True,' which is helpful for understanding what the tool does. However, it doesn't elaborate on the exact algorithmic nature of what makes it a 'second ring' or if there are any side effects.
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, directly explaining the tool's purpose in a few sentences and providing a clear text representation of the return type. The structure effectively separates the primary purpose from the output definition, making it easy to parse 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?
Despite the lack of an output schema and annotations, the description provides a good understanding of the tool's purpose and output. It clarifies the one parameter it has and explains the structure of the response, covering the required bases for a tool of this low-level complexity.
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?
With 0% schema description coverage, the parameter `tag` depends entirely on the description. The description explicitly clarifies, 'tag: filter to one shelf tag, empty = everything,' adding significant meaning about the filtering behavior and default behavior that goes beyond the raw type definition in 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 it finds 'A second ring of verified sources that are not on the default shelf,' which gives a specific purpose and implicitly distinguishes it from other tools like shelf_add or shelf. While it's clear, it doesn't explicitly name sibling tools for direct differentiation.
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 shows how to act on the output by saying 'shelf_add(url=its url, name=its name)', which implies a workflow, but does not explicitly clarify the difference between 'second ring' and 'default shelf' or when to prefer this over the alternative 'shelf' tool for direct listing. Clear usage context is implied but not explicitly spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tonight's sky: moon phase, illumination, moonrise/set, sunset, next full/new moon, and which naked-eye planets are up at 21:00.
Computed locally (set ENGAWA_LAT / ENGAWA_LON for your location) — the one tool here that never touches the network.
Args: date: "YYYY-MM-DD"; empty = today (local timezone)
Returns: {ok, date, moon_phase, moon_illumination, moonrise, moonset, sunset, next_full_moon, next_new_moon, planets_2100}
| Name | Required | Description | Default |
|---|---|---|---|
| date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral aspects: it computes locally, requires environment variables (ENGAWA_LAT/ENGAWA_LON), and never touches the network. It also specifies the return structure and date handling, offering complete transparency beyond what structured fields would 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?
The description is well-structured and front-loaded with the core purpose, then concise details about computation and arguments. Every sentence adds value, and the return format is listed clearly. There is no redundancy or 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 (one optional parameter) and no output schema, the description covers all necessary context: the exact computation method, network behavior, environment prerequisites, and the full list of returned fields. It is complete for an agent to select and invoke correctly.
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 single parameter 'date' is fully explained: it must be in 'YYYY-MM-DD' format, and an empty string defaults to today in the local timezone. This adds substantial meaning beyond the schema, which has no description for the parameter.
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 defines the tool's purpose: it provides tonight's sky information including moon phase, illumination, rise/set times, sunset, next full/new moon, and visible planets. This is specific and distinct from sibling tools like apod or daily_art, which focus on other content types.
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 indicates this is the only local, network-free tool, implying it should be used when offline or for sky data. It also explains the optional date parameter. However, it does not explicitly contrast with alternatives or state when not to use it, so it stops short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read any web page: give a URL, get title + clean article text + links.
Two lanes inside: httpx + readability for static pages (fast), and an
automatic fallback to a real browser render for SPAs (needs the optional
engawa-mcp[browser] extra). Long articles: page through with offset,
watching total_length.
Boundaries:
No login state, no history. To "click" a link, call web_read again with that link's URL.
Login-walled platforms (x.com etc.) won't yield anything useful.
Args: url: full URL (http:// or https://) offset: character offset into the article text (for paging) length: max characters returned this call (default 3000)
Returns: {ok, title, content, total_length, links (≤10), note}
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| length | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so admirably. It discloses the asynchronous fallback to a browser renderer for SPAs, the optional dependency (`engawa-mcp[browser]`), the stateless nature (no login/history), and the limitation with login-walled sites. This is exactly the kind of behavioral context that helps an agent set expectations.
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?
Despite its length, the description is well-structured with clear labels (Boundaries, Args, Returns) and front-loaded with the core purpose. Every sentence adds value—the implementation detail of static vs. browser fallback is relevant for performance expectations, and the 'note' field disclosure avoids surprising the 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?
Given the absence of an output schema, the description specifies the exact return shape ({ok, title, content, total_length, links (≤10), note}) and clarifies edge-case behavior (e.g., pagination, link following). This makes the tool fully usable without external documentation, which is especially valuable for a tool with no annotations.
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?
Input schema has 0% description coverage, so the description compensates fully. The Args section explains `url` (full URL with scheme), `offset` (character offset for paging), and `length` (max characters, default 3000). It also explains the behavior of the return fields, particularly `total_length` for pagination.
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 clear verb and resource: 'Read any web page: give a URL, get title + clean article text + links.' It clearly differentiates the tool from siblings by focusing on generic web fetching, which is distinct from the more niche sibling tools like rss_read and shelf. The output contract (title, content, links) is explicit.
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 guidance on when to use: 'No login state, no history,' 'To "click" a link, call web_read again,' and explicitly excludes login-walled platforms like x.com. It also explains the two execution lanes (static vs. SPA fallback) and paging, giving the agent clear context about boundaries and alternatives.
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.
v0.1.0apodarxiv_newdaily_artdaily_poemon_this_dayrss_readshelfshelf_addshelf_removeshelf_suggestsky_tonightweb_readScored across 12 tools
Each tool is highly distinct: rss_read and web_read/shelf/sky_tonight/apod/daily_art/arxiv_new/daily_poem/on_this_day all target clearly separate content sources and purposes. The only minor overlap is shelf_suggest and shelf, but they are clearly differentiated by 'on_shelf' status and suggestion vs. current shelf.
Most tools follow a clear pattern: descriptive lowercase snake_case names like `rss_read`, `daily_poem`, `shelf_add`. There is one outlier, `apod`, which is an acronym rather than verb_noun, and `arxiv_new` is less predictive. However, overall the naming is intuitive and mostly consistent.
12 tools is well within the ideal range for a curator/reader server. Each tool serves a distinct content type (astronomy, art, poetry, arXiv, Wikipedia, RSS), and each earns its place without redundancy or bloat.
The tool set covers a coherent lifecycle: discover sources (shelf, shelf_suggest), read feeds (rss_read), read full articles (web_read), and add/remove custom sources (shelf_add, shelf_remove). Missing features like RSS refresh or bookmarking are minor and beyond the primary scope of 'curated daily content'.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Dive into the latest and greatest from the tech world with our Hacker News MCP server.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
MCP server for Project Gutenberg — 75,000+ public-domain ebooks with full plain-text retrieval.
