A
licenseNot graded
qualityA
maintenanceExposes an agent orchestration task queue as an MCP tool interface, allowing agents to submit, list, get, and update tasks with typed validation.
3
MIT
hearthsmith
by Eyalm321
This server exposes a task-management MCP interface for the hearthsmith blacksmith pet.
List tasks — fetch tasks by state (
open,done,blocked,delegated,all) and optionally filter by project.Add tasks — create a task with a title, optional due date, tags, notes, and project.
Mark tasks done — complete a task using its ID or a unique ID prefix.
Block tasks — mark a task as blocked so the pet stops nagging about it, optionally with a reason.
Snooze tasks — pause nagging for a task for a configurable number of minutes (default 120).
View recent nags — inspect what the blacksmith said recently and the decision behind each nag.
Allows the desktop agent to observe and automate Firefox browser pages through the AT-SPI accessibility tree, including interacting with page content, activating buttons, switching tabs, and filling fields.
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., "@hearthsmithshow me my overdue tasks"
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.
hearthsmith
A pixel-art blacksmith who lives on your desktop, nags you about your tasks, watches your terminal panes, and hands work to your coding agents.
Formerly forge. Renamed because nobody can find a project called forge.
Harness-agnostic: hearthsmith owns the task store (SQLite) and exposes it over MCP, so Claude Code, dsh, Codex, OpenClaw or a shell are all just clients. hyperpanes is first-class: the pet reads what you're doing from your panes, nags you in the relevant pane, and can hand a task to a worker pane instead of nagging.
timer ─▶ hearthsmithd heartbeat
├─ T0 sense hyperpanes /state + /projects + pane screens, tasks.md, the store (no model)
├─ T1 decide Jev typed decision: nag? which task? urgency? channel? (~400ms / ~$0.00002)
├─ T2 compose Ornith-1.5-9B on a local Ollama writes the blacksmith's line (free, private)
├─ T3 fallback OpenRouter chat model when the local box is asleep
└─ deliver notify-send | hyperpanes pane message | delegate to a worker queue
+ writes sprite.json for the avatar renderer
+ says it out loud in his own voice (AuK clone, see Voice)Every stage degrades: no hyperpanes → store-only state; decider down → rule heuristics; Ollama down → OpenRouter → template. The loop never goes silent because a dependency did.
Install
uv sync && uv pip install -e .
hearthsmith add "temper the blade" --due 2026-09-20T18:00 --project hearthsmith
hearthsmith state # the exact paragraph the decider sees
hearthsmithd --once --dry # decide + compose, deliver nothingTell him a reminder the way you'd say it — "remind me to call the vet friday at 5pm", "don't let
me forget rent tomorrow morning", "in 20 minutes take the bread out" — and it lands on the ledger
as call the vet, due Fri 17:00, and he says the time back. Dates are read locally
(src/hearthsmith/when.py, no model); a day with no time is due by 18:00 that day. Only when you
name no time at all does the decider guess one. The ledger's add box reads the same words.
Tasks can repeat — "water the plants every monday", "standup every weekday at 9:30",
"daily vitamins at 9pm", "pay rent monthly", or @every(mon,thu) / @every(2 weeks) in tasks.md
and the ledger. Ticking one off, however it's ticked (ledger, CLI, MCP, "that's done"), puts the
next occurrence on the ledger; done three days late, the next one is still ahead of you rather
than a backlog of three. And tasks can have steps: ledger → Add step…, hearthsmith add --parent <id>, or let the compose model cut it up — "break down the site launch", ledger →
Split into steps, hearthsmith split <id>. A task with open steps is nagged about by its next
step ("write the copy (step of 'the site launch')"), carrying the task's due date; finishing the
task finishes its steps.
Any task can be handed to an agent: ledger → Hand to agent, "give the changelog to an
agent", hearthsmith hand <id>, or hearthsmith_tasks_hand over MCP. It goes to a Claude pane
already on that work in the task's project if there is one, else a new pane in the project's
folder, briefed with the title, notes, open steps and an ask to finish with a short report. The
task moves to the ledger's Agents tab. When the agent goes quiet, the heartbeat reads its
last reply from Claude Code's session transcript (the screen scrape is the fallback), appends it
to the task's notes, puts the task back in Open marked agent reported — check it, and tells
you. He doesn't tick it off for you. Take back (or hearthsmith hand --back <id>) stops
waiting on the agent.
He remembers you. Tell him how you work — "I don't want nags before 10", "don't nag me
about email", "the site launch matters most this week", "weekends are mine", "I work best in
the evenings" — and he keeps it. The ones with a plain meaning become rules he obeys: quiet
hours tightened (the morning brief waits too), whole weekends off, a topic never nagged about
(it stays on the ledger), a focus whose tasks come first until it expires. Everything else goes
into what the decider and his voice read. He also notices, from the store: the hours you actually
finish things, and tasks nagged about again and again without moving — for those he suggests
splitting or handing off instead of repeating himself. "What do you know about me", "forget
that…", the ledger's Memory tab (× to forget), hearthsmith memory [add|forget], and
hearthsmith_memory_list / _add / _forget over MCP.
When nagging isn't working he offers to do something about it. A task nagged 4 times
(nag.stuck_after) with no steps and no movement gets an offer instead of a fifth nag: "'do the
taxes' has sat through 5 nags… want me to split it into steps? Or hand it to an agent, or leave it
be." He recommends a hand-off when the task belongs to a project with a folder, a split
otherwise, and does neither until you answer — "split it", "hand it off", "yes" (his pick) or
"no" — to him or from the ledger, where a stuck task is marked and its ⋯ menu has Leave it be.
"No" stops the offers and the nags for that task until its date moves or it gets a step. An
unanswered offer can come back after three days.
He reads your calendar from its private iCal link — Google's Secret address in iCal
format, Outlook's published ICS link, iCloud's public calendar link, Proton's share link, or a
local .ics. Put it in ~/.config/hearthsmith/env as HEARTHSMITH_CALENDAR=<url> [<url>…] (the
link is a password to your calendar, so it lives with the other secrets and never in a log).
Repeating meetings, exceptions and timezones are expanded; feeds are fetched every 15 minutes and
the last copy is used when a fetch fails. He gives a heads-up 10 minutes before each meeting,
holds nags while you're in one, knows the next event when deciding what to say, puts today's
meetings in the morning brief and tomorrow's in the evening wrap, and shows the rest of today at
the top of the ledger. Ask him "what's on my calendar tomorrow" or "when's my next meeting";
hearthsmith cal, hearthsmith_calendar over MCP. Settings under calendar:.
Twice a day he tells you where things stand. The morning brief (from 08:30): what landed
overnight — answers, agents that finished or didn't — what's overdue, what's due today, what's
stuck, which panes are waiting on a yes. The evening wrap (from 18:30): what you struck off,
what's still open, what's due tomorrow; an evening with nothing to say is skipped. Each comes
once a day, on the sprite and in his voice, and waits until you've touched the keyboard or mouse
in the last two minutes (GNOME's idle monitor) so it greets you rather than an empty room. The
facts come from the store with no model; the compose model only phrases them, a template when
it's down. On demand: "brief me" / "what's on my plate", Brief me in his menu,
hearthsmith brief [morning|evening], or hearthsmith_brief over MCP. Times in brief: config.
Once a week (Friday from 16:00, brief.weekly_day / brief.weekly) comes the weekly
review: how much you struck off and how much of it late, the busiest day, how the focus went,
what the agents took and brought back, what's still overdue, what's been carried all week or
nagged about for nothing (with what to do about it), then next week — what's due and how full the
calendar is — ending with "what's the focus next week?". Answer "focus on the launch next week"
and it's set through next Sunday. Same delivery as the daily brief; on demand with "how did my
week go", Weekly review in his menu, hearthsmith brief weekly, or hearthsmith_brief with
kind weekly.
Talk to him out loud. Press Super+J, say it, stop talking: he hears it, does it, and
answers aloud. Press it while he's talking and he stops to listen; talk over him and he stops too.
Conversation mode (his right-click menu, or hearthsmith-ear talk) keeps him listening
after each answer until you say "that's all" or go quiet for 45 seconds. He remembers the last
ten minutes of what you said to each other, typed or spoken, so "remind me to order filament
Friday" then "actually, move it to Monday at ten" moves that task. Speech is transcribed on your
GPU by faster-whisper (large-v3-turbo, ~0.3s for a sentence); audio never leaves the machine, and
the mic (ear.source) is open only during a turn or a conversation. The listener is
hearthsmith-ear.service; settings under ear:.
Ask him a question and he answers it rather than reporting that a page was opened. One page holds it ("what does the P2S cost") → he opens the page and reads it, a couple of seconds, and says so plainly when the page doesn't actually contain it. It needs comparing sources ("what do people charge on average", "compare X and Y") → he puts an agent on it in its own pane and brings the answer back on the next heartbeat, attached to the task.
Everything he is asked to do is recorded: the goal, which body ran it, whether it worked, the
steps he took with their confidence and decision latency, and what the verifier saw. hearthsmith runs
lists them, hearthsmith runs <id> shows one. Values you typed into his dialog are stored as
"(from you)" — a credential never reaches the history.
Config: ~/.config/hearthsmith/config.yaml (every key optional, see src/hearthsmith/config.py).
State: ~/.local/state/hearthsmith/ (hearthsmith.db, sprite.json).
Decide backends (decide.backend)
key | what | status |
| TypeSafe Jev via OpenRouter's Decisions router | default |
| Jev direct at | needs early-access key |
| MIT system-one-adapter over any OpenAI-compatible chat model (~20s) | last resort |
| overdue + gap heuristics, no model | always-on fallback |
Same Noul / Score / Choice questions in every backend — swapping is a config key.
Related MCP server: task-manager-mcp
MCP
claude mcp add hearthsmith -- $(pwd)/.venv/bin/hearthsmith-mcpTools: hearthsmith_tasks_list / _get / _add / _edit / _done / _reopen / _block / _snooze / _delete / _split / _hand, hearthsmith_memory_list / _add / _forget, hearthsmith_calendar, hearthsmith_brief, hearthsmith_nags_recent.
tasks.md
Zero-dep importer. - [ ] title @due(2026-09-20) @every(mon) +project #tag. One-way: file → store; tick the box
to mark done. hearthsmith never writes the file.
hyperpanes
Reads ~/.local/state/hyperpanes/control.json for port + token. Nags go through
POST /panes/{id}/messages (out-of-band, to the pane's agent). POST /panes/{id}/input is
arbitrary command execution and stays off unless hyperpanes.allow_pane_input: true.
Delegation enqueues to hyperpanes.delegate_queue (default hearthsmith); drain it with
hyperpanes worker --queue hearthsmith -- <cmd>.
Avatar
An always-on-top, click-through GTK window (hearthsmith-sprite.service) that polls
sprite.json (state ∈ idle | forge | alert | sleep, text, urgency) and plays the matching
frames from a sprite pack sliced out of assets/sheets/. Left click talks to him, drag moves him,
middle click opens his ledger, right click is the menu (ledger, size, corner, sheet, nag now, hide).
The ledger is the task list as a window, read straight from the store — a task an agent adds
over MCP appears within a couple of seconds. The add box takes the tasks.md syntax
(quench @due(2026-09-25T18:00) +forge #hot); tick = done, click a row = its notes and the runs
he made for it, ⋯ = edit / snooze / block / delete. Open / Blocked / Done tabs, Ctrl+N to add,
Esc to close. python3 -m hearthsmith.sprite.ledger opens it without the avatar. Position and size persist in
~/.config/hearthsmith/avatar.yaml. If the frame clock stalls he remaps himself, then restarts.
While either body works, the avatar narrates it — "clicking One way", "typing Where from? = 'Zurich'" — so a task running in his Chrome is still visible on your desktop. Progress lines skip the typewriter and expire in seconds; a nag still types out and stays.
Work aimed at an agent goes to the right one: panes already in that project are candidates, each described by what it is actually doing (its last few lines, not its label), and the question is whether the assignment continues that work or is a separate concern deserving its own agent. A busy agent is only interrupted when it really is the same thread of work.
Voice
He sounds like a dwarf. assets/voice/dwarf.wav is 16s of WoW dwarf NPC lines (dwarf.txt its
transcript); a zero-shot cloner says each line in that voice, so the clip is the voice — drop
in another wav (voice.ref + voice.ref_text) and he is someone else. Engines, tried in order
(voice.engines), same clip into all of them:
pocket — Pocket TTS (Kyutai, 100M, MIT code / CC-BY-4.0 weights). 2 CPU cores, streams PCM straight into
pw-play: first sound ~0.2s, RTF ~0.6 here. Clip only, no transcript. Weights are gated — accept terms once at hf.co/kyutai/pocket-tts. Default.auk — AuK (Tencent, MIT) on the HF space. Best clone; ~17 GiB so it can't run here, ~8 free lines/day, ~20s a line.
qwen — Qwen3-TTS-0.6B-Base (Apache-2.0) on the GPU, fp32 (fp16 NaNs on Turing), ~RTF 1.5. Kept for A/B.
pocket and qwen live in one warm server: contrib/voice-server (hearthsmith-voice.service,
:7861); Qwen unloads after 15 min idle, Pocket stays. Wavs are cached by text+clip+engine under
~/.local/state/hearthsmith/voice/. Playback is pw-play to the default sink, blocking, because
hearthsmithd is a oneshot unit. Research behind the pick: docs/research/realtime-clone-tts.md.
forge speak "Oi. That ledger's got rust on it." # hear him; --no-play prints the wav pathsSuggestions
After a turn, a Claude pane can offer its own next prompt as ghost text in its input box
(Claude Code "prompt suggestions"; staged rollout, so it appears sometimes — force with
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=true; never on the first turn, in plan mode, or while a
permission is pending). He watches idle panes for one, and once it has sat unchanged for
hyperpanes.suggestion_settle_s (20s — the screen is plain text, so ghost text and a line you
are typing look the same) he tells you once: "'canora-sync' wants to: run the tests. Yes or
no?", with how many sibling panes in that project are still busy. hearthsmith suggestions
lists them. That is hyperpanes.suggestions: observe (or off).
accept goes further, in panes he spawned only (meta.owner=hearthsmith — yours are only
ever reported): Jev judges each settled suggestion accept / wait / dismiss / ask, with the
pane's last answer and its siblings' state (same meta.goal when the goals org stamps one, else
same directory). Accept = Tab, Enter — named keys, no text can go in that way — pressed only if
the input line still reads what was judged (the pane regenerates suggestions while they sit).
Busy siblings mean wait, no call made. Anything irreversible comes back as dismiss or ask; ask
is the fallback when the decider is down. Every verdict is a run (hearthsmith runs).
Panes an agent org spawned for itself (goal-orchestrator skill: meta.role=spec|impl,
meta.goal) count as his too (suggestion_accept_roles); the goals orchestrator itself is
report-only, its suggestions are goal-level. For those, one more step before Jev: he gathers
what the org already emits — the spec agent's text, siblings' last words, reports on the pane
message bus, subtask states in the goal's work queue — and compose.judge_model (MiMo v2.6
flash on OpenRouter, ~$0.001, ~3s) condenses it into one paragraph Jev reads, plus a depends on
unfinished work score that forces wait over accept. Observed on a real queue: "run the tests"
waits at 0.90 while the sibling's subtask is claimed, accepts at 0.92 once it is done; "git push"
dismissed at 0.85. Design: docs/suggestions-stage3-scope.md.
Two bodies, one brain
Jev decides; where the hands are depends on the job.
errand | body |
anything in a web page | his Chrome — browser-use/jev-ultrafast (MIT) over CDP |
everything else | your desktop — AT-SPI + uinput, quiet by default |
Inside a page a DOM snapshot wins and it isn't close: the page owns its state machine and
ignores anything that isn't a real DOM event, so a site like Google Flights beats synthetic
input. Two upstream lines are wrapped rather than forked — decisions go to the OpenRouter
Decisions router (the Jev access this machine has), and the tab opens in the foreground so you
can watch. He gets his own Chrome profile because Chrome 136+ refuses remote debugging on the
default one; hearthsmith web "<goal>" runs it directly, and the browse intent routes there.
Computer use
He works in your apps, on screen — no headless browser, no remote-debugging ports, no
separate profile. Quiet by default: he never touches your mouse or keyboard, so he can work
while you work. Widgets are activated through AT-SPI actions (switch a tab, activate a
button), fields filled through EditableText, web addresses opened straight in the browser.
--hands lets him drive the shared cursor for the widgets that expose no action — that one is
exclusive, and he stops the moment the pointer wanders off where he left it. Observe = AT-SPI2 accessibility tree (every GTK/Qt/
Electron app and Firefox/Chromium page content), decide = Jev (typed Choice over the visible
elements, ~0.5s), act = AT-SPI actions first, /dev/uinput only under --hands.
Setup (once):
gsettings set org.gnome.desktop.interface toolkit-accessibility true(install.sh does it)the
hearthsmith-windowsGNOME Shell extension (contrib/gnome-extension, install.sh copies it; enable + log out/in once). Wayland hides window positions from clients; the extension exposes frame rects over the session bus, read-only.user in the
inputgroup (for/dev/uinput).
One Jev request per cycle carries speculative heads — the operation plus a target for each operation that needs one, each head offering only compatible elements — so whichever operation wins already has its target. Before acting he re-reads the element (gone, hidden or moved ⇒ re-observe instead of clicking blind), and after acting he waits for the tree to actually change rather than sleeping a fixed amount. Those three ideas come from browser-use/jev-ultrafast (MIT), which does the same thing for Chrome over CDP; hearthsmith keeps AT-SPI + uinput so it works in every app, in the windows you can see.
Before reporting success he takes one look: a screenshot of the window goes to the local
vision model with the goal, and "YES / NO + why" decides whether the run is really done. That
catches what the accessibility tree can't express — a form that is filled in but still has its
date picker open over it reads as plausible text and looks obviously unfinished. Once per task,
never per step; if the extension or the model is missing it says so and keeps the original
verdict. desktop.verify: false turns it off, hearthsmith-look "<goal>" runs it by hand.
hearthsmith do "in Firefox, search for 'lw-pla filament'" · hearthsmith windows shows what he sees.
Custom-drawn surfaces (games, terminal grids) are invisible to AT-SPI — screenshot+vision is the
fallback there, not built yet.
Available Tools
6 toolshearthsmith_nags_recentB
What the blacksmith said recently, with the decision that drove it.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It transparently implies a read-only retrieval ('what ... said recently') and adds that each result includes the driving decision, but it does not disclose ordering, filtering semantics, or whether the call has any side effects. This is a minor gap for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler and places the core idea first. It is concise, though slightly cryptic due to the blacksmith metaphor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one optional parameter and an output schema, the description does not need to explain return values. However, it leaves the meaning of 'nags' and the n parameter implicit, and it does not orient the agent against the sibling tools, so completeness is adequate but not strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the sole parameter n. The name and default hint suggest it is a count, but the description fails to clarify whether n limits the number of results, a time window, or pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys that the tool retrieves the blacksmith's recent statements (nags) and associates them with the decision that prompted them, which is a clear resource and action even though phrased as a question rather than an imperative. It differentiates from the tasks_* siblings by focusing on the blacksmith's communications/nags rather than task state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to choose this tool over siblings such as hearthsmith_tasks_list or hearthsmith_tasks_done, nor any exclusions or prerequisites. The intended use must be inferred from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hearthsmith_tasks_addB
Add a task. due is ISO date/datetime (local). project is a hyperpanes project id or name.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due | No | ||
| tags | No | ||
| notes | No | ||
| title | Yes | ||
| project | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.2/5.0
Behavior2/5
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 discloses only that the operation adds a task and clarifies parameter formats, but it does not state side effects, permission requirements, idempotency, error behavior, or what happens after creation. This is a meaningful gap for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core operation is front-loaded, and the additional sentence adds directly useful parameter context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description is thin for a tool with five parameters and no annotations. It omits usage guidance, behavioral effects, and semantics for some parameters. An agent would still need to guess about expected input formats for tags and notes and what to do after the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It usefully explains that due is an ISO date/datetime in local time and that project accepts a hyperpanes id or name. However, tags, notes, and title are left to inference from their schema titles, so the compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource, 'Add a task,' which clearly distinguishes it from sibling tools like hearthsmith_tasks_done, hearthsmith_tasks_list, hearthsmith_tasks_block, and hearthsmith_tasks_snooze. The extra details about due and project reinforce what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The creation purpose is implied by the verb 'Add,' but the agent is given no explicit decision context relative to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hearthsmith_tasks_blockB
Mark a task blocked (the pet stops nagging about it).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| task_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does reveal a key behavioral outcome ('the pet stops nagging'), but it does not explain whether blocking is reversible, how it interacts with other task states, or what side effects occur beyond the nagging behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, and the core action is front-loaded. It earns a high score for structure, though it sacrifices informative content for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter tool with an output schema, so the missing return-value documentation is not a concern. However, the description does not explain how blocking differs from marking done or snoozing, nor what 'blocked' implies for future task behavior. It is minimally viable for invocation but not fully contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate, but it does not. task_id is inferable from its name and required status, but the purpose and effect of the optional 'reason' parameter are entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Mark a task blocked') and a concrete consequence ('the pet stops nagging about it'). It clearly identifies the resource and operation, though it does not explicitly contrast with sibling tools like done or snooze, which also affect nagging behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use block versus alternatives such as hearthsmith_tasks_done or hearthsmith_tasks_snooze. The parenthetical describes the effect but leaves the decision entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hearthsmith_tasks_doneA
Mark a task done. Accepts an id prefix.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a useful behavioral trait—accepting an id prefix—but does not mention whether the action is reversible, what happens to already-done tasks, or any side effects. Core behavior is stated, but edge-case behavior is left unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with the primary action front-loaded and the parameter nuance in the second sentence. There is no fluff or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter and an output schema, the description is mostly adequate. However, it lacks usage guidance and any detail about ambiguous prefixes, repeated calls, or state-transition consequences. It is serviceable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides the parameter name 'Task Id' with no description. The tool description adds real meaning by explaining that the id can be a prefix, which is critical for correct invocation. Without this, the agent would likely assume an exact ID is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a precise verb-resource statement: 'Mark a task done.' This clearly distinguishes it from siblings such as list, add, block, and snooze. The second sentence about id prefix adds a useful constraint without muddying the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives like block or snooze. No context, prerequisites, or exclusions are provided, leaving the agent to infer the appropriate situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hearthsmith_tasks_listA
List tasks. state: open | done | blocked | delegated | all. project filters by hyperpanes project id/name.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | open | |
| project | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden. 'List' implies a read-only operation, and the state values are enumerated, but the description does not disclose pagination, sorting, or any side effects. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action ('List tasks'), and immediately clarifies the key parameters. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return details are not needed. The description covers the essential filtering options and states the allowed state values. Minor omissions like pagination or default behavior are acceptable for a simple list tool, so it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully explains both parameters: state lists all allowed values (open, done, blocked, delegated, all) and project filters by hyperpanes project id/name. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List tasks,' a specific verb and resource, and clearly distinguishes this from siblings like hearthsmith_tasks_done, hearthsmith_tasks_add, etc. It is unambiguous that this tool retrieves a collection of tasks, not modifies them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides filter options (state, project) and implies this is the general listing tool, but it does not explicitly state when to prefer this over siblings such as hearthsmith_tasks_done or hearthsmith_nags_recent. It gives context but no exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hearthsmith_tasks_snoozeC
Snooze nagging for a task.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| minutes | No | ||
| task_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only says 'snooze nagging.' It does not disclose that the task remains open, that the snooze is temporary, that minutes controls the delay, or what effects this has relative to done and block. These are important behavioral traits for a mutation-like task action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no filler and leads with the action. It is concise and readable, though the brevity comes at the cost of missing useful guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity and the presence of an output schema, the description omits the key distinction from sibling tools (done/block) and the role of the minutes parameter, which an agent needs to choose and invoke the tool correctly. It is minimally understandable but incomplete for confident use in a task-management family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the input schema. It only hints at task_id via 'for a task' and minutes via the verb 'snooze'; it never mentions the default duration, units, or which parameter is required, leaving the schema to do all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Snooze nagging for a task" states a specific verb (snooze) and resource (nagging/reminders for a task), which distinguishes it from sibling actions like done, list, and add. It is weaker than a 5 because it never explicitly says the reminders are temporarily postponed, leaving some ambiguity with block.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use snooze versus finishing (done), blocking (block), or reviewing nags (nags_recent). An agent must infer the selection criteria from the tool name and sibling list, so the description fails to provide context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v0.1.0- First observed
hearthsmith_nags_recent - First observed
hearthsmith_tasks_add - First observed
hearthsmith_tasks_block - First observed
hearthsmith_tasks_done - First observed
hearthsmith_tasks_list - First observed
hearthsmith_tasks_snooze
TDQS
A3.5/5.0
Scored across 6 tools
Disambiguation5/5
Each tool targets a distinct action: adding, listing, marking done, blocking, snoozing, and viewing recent nags. No two tools have overlapping purposes, so an agent can easily select the correct one.
Naming Consistency4/5
Most tools follow the pattern hearthsmith_tasks_<verb> (add, list, done, block, snooze), but 'done' is a past participle rather than a verb, and 'nags_recent' uses an adjective instead of an action. The prefix is consistent and the deviations are minor.
Tool Count5/5
Six tools is well-scoped for a task management server with a nagging feature. Each tool fills a clear role, and the count feels neither thin nor bloated.
Completeness4/5
The surface covers the core lifecycle: create (add), read (list), and multiple state updates (done, block, snooze). Missing a general edit or delete, but the domain does not clearly require them, and the existing operations cover the main workflow without dead ends.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Project management MCP for AI agents with safe task reads and writes.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceA task manager MCP server that demonstrates all three MCP primitives (tools, resources, prompts). Enables users to manage tasks, read task summaries and details, and run structured planning/review prompts through natural language.-
- AlicenseNot gradedqualityBmaintenanceEnables agents to manage personal task lists through the MCP protocol, supporting task creation, editing, completion, deletion, grouping, reordering, and JSON import/export.1AGPL 3.0
- FlicenseNot gradedqualityBmaintenanceEnables personal productivity management by exposing MCP tools to create, retrieve, list, update, complete, and delete tasks and calendar events, with validation and conflict detection.-