What can you do with this server?

agent-postit is a local MCP server that provides AI agents with a persistent, file-based memory system for managing markdown notes and topics. All notes and topics are stored as plain Markdown files under ~/.agent-postit/ (configurable). Communication uses MCP over HTTP on loopback (127.0.0.1:8000) with a stdio fallback. Topic Management * topic.create: Create hierarchical topic directories and their TOPIC.md descriptions; idempotent and supports top-down construction. * topic.read: Retrieve the description of a topic directory. * topic.write: Overwrite the description of an existing topic. Note (Postit) CRUD * postit.create: Write a new note into a topic directory; fails if the note exists or directory isn't a topic. * postit.read: Retrieve a note's full body, metadata (mtime, size). * postit.rename: Rename a note within its directory. * postit.delete: Remove a note file. * postit.update_body (or its aliases append/overwrite): Atomically append to or overwrite a note's body, with a 1 MiB size cap. Aliases: postit.append and postit.overwrite for clarity. Partial Reading * postit.read_section: Extract a specific Markdown section and sub-sections by heading text (case-insensitive). * postit.read_lines: Read a 1-based inclusive line range from a note. Discovery & Search * postit.ls: List directory contents (notes and topics) with metadata like mtime and size, or list headings of a note; supports recursive listing. * postit.search: Case-insensitive regex search across note names and/or bodies, optionally recursive; returns matching lines and line numbers. * postit.recent: List recently modified notes across the store, sorted by mtime (useful for session start). Introspection * postit.capabilities: Get server name, version, store root, and a list of all registered tools with annotations (read-only, destructive, etc.). All operations are local, and names are case-folded to lowercase for consistency. Error responses include specific error codes (e.g., not_found, dir_exists, too_large).

How do I use agent-postit?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-postit remember that the project deadline is Friday" 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.

agent-postit

by gerelef

Overview Schema Related Servers Score Discussions

Python

Local

agent-postit

agent-postit is a small local server that gives an AI agent a place to scribble notes — a memory, so things it learns in one session are still around in the next.

Think of it like a corkboard with sticky notes. The agent writes a note when it picks up something it wants to recall later (a fact, a decision, a checklist, a bug it's chasing), files it under a topic, and glances at the board at the start of the next session to remember where it left off.

It speaks MCP over HTTP on 127.0.0.1:8000, so any MCP-aware editor or agent (Zed, a CLI harness, another agent) can point at it. Notes are plain Markdown files on your disk under ~/.agent-postit/ — nothing is hidden in a database, so you can read, grep, and edit them by hand too.

There is no auth. The server binds on 0.0.0.0, intended for use with podman; whoever can reach your machine on the bound port can read and write notes. Make sure you bind the image on loopback.

Build, install, run

You need Python 3.12+ and uv.

git clone https://github.com/gerelef/agent-postit.git && cd agent-postit
uv sync                       # install deps (incl. dev) into ./.venv
uv run python -m agent_postit # serves MCP at http://127.0.0.1:8000/mcp

Liveness probe (no client needed):

curl -s http://127.0.0.1:8000/healthz   # → ok

Override the data root / host / port via flags or env:

uv run python -m agent_postit --root ./my-notes --port 8011
# or
POSTIT_ROOT=/var/lib/agent-postit POSTIT_PORT=8011 uv run python -m agent_postit

Container (podman or docker)

A prod-ready multi-stage image is published on Docker Hub at gerelef/agent-postit. Tags track releases; :latest rolls forward with each one, and tagged releases (e.g. :v1.0.0) are immutable. Pull:

podman pull docker.io/gerelef/agent-postit:v1.0.0
# or, to float on the rolling tag:
podman pull docker.io/gerelef/agent-postit:latest
# docker is identical (docker.io/ is the default registry):
docker pull gerelef/agent-postit:v1.0.0

Run (HTTP transport — bind loopback on the host side, no -i, no -t):

podman run --rm --name agent-postit \
  -p 127.0.0.1:8000:8000 \
  -v ~/.agent-postit:/data:Z \
  docker.io/gerelef/agent-postit:v1.0.0

# docker works the same (drop the :Z suffix):
docker run --rm --name agent-postit \
  -p 127.0.0.1:8000:8000 \
  -v ~/.agent-postit:/data \
  gerelef/agent-postit:v1.0.0

The 127.0.0.1: prefix on the publish flag is the loopback guarantee — do not drop it unless you intend to expose the port to other hosts (and have a reverse proxy with auth in front).

Building from source (optional)

The repo also ships a multi-stage Dockerfile; Containerfile is a symlink to it (podman convention). Use this only if you want a local build or a custom tag — the published image above is the same Dockerfile.

podman build --format docker -t agent-postit:latest .
# docker uses the docker image format by default, so no flag is needed:
docker build -t agent-postit:latest .

--format docker makes podman emit the Docker image format so the HEALTHCHECK instruction in the Dockerfile is honored (OCI format, the podman default, has no HEALTHCHECK field and silently drops it).

Under `systemd --user` (rootless quadlet)

A reference rootless quadlet is shipped at contrib/agent-postit.container. Quadlet (podman 4.4+) is podman's native systemd integration: drop a .container file under ~/.config/containers/systemd/, reload systemd, and the podman generator emits a regular agent-postit.service from it on boot — no hand-written podman run line in the unit.

The shipped quadlet pulls docker.io/gerelef/agent-postit:v1.0.0 from Docker Hub by default (edit Image= for a different tag or a local build). Install and start:

mkdir -p ~/.config/containers/systemd
cp contrib/agent-postit.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user enable --now agent-postit.service
journalctl --user -u agent-postit.service -f  # follows stdout/uvicorn
systemctl --user status agent-postit.service  # verify everything works

To pin a different tag, change Image= in the installed agent-postit.container (or the local copy under contrib/) and systemctl --user daemon-reload && systemctl --user restart agent-postit.service.

Related MCP server: basic-memory-mcp

Tools

The server advertises 15 tools under the agent-postit MCP server name. Tools surface to clients as mcp:agent-postit:<tool> (e.g. mcp:agent-postit:postit.recent). All tools take a single object argument named arg over the wire. Paths are addressed by (dir, name) — there are no integer IDs. dir defaults to the root /.

Notes are .md files; the filename (minus .md) is the note's name. Both dir and name are case-folded to lowercase on the way in — creating a note called Recall lands on disk as recall.md, and reading/listing/deleting it accepts any case. TOPIC is a reserved name (case-insensitive: Topic, topic, TOPIC all rejected).

Topic tools

topic.create — dir (required), description (required, may be ""). Creates the directory and writes TOPIC.md with the description. Idempotent: a repeat call with the exact same dir + description byte-matching the existing TOPIC.md body is a no-op success (safe to retry). Refuses with dir_exists if dir already exists but the existing TOPIC.md body differs (or TOPIC.md is missing — e.g. a stray foreign directory); refuses with dir_missing if the parent dir is not already a topic (with a hint to create the parent first). Topics are built top-down, one level at a time. This is the only way to make a new topic.
topic.read — dir (required). Returns the TOPIC.md body for that directory, or null if missing.
topic.write — dir (required), description (required). Overwrites TOPIC.md. Refuses if the directory is missing.

Postit CRUD

postit.create — name (required), body (required, may be ""), dir?. Writes <dir>/<name>.md atomically. dir_missing if the dir is not a topic; already_exists if the file is there.
postit.append — name (required), content (required), dir?. Reads the existing body, concatenates content (inserting a trailing newline when the existing body is non-empty and lacks one), and writes back atomically behind a per-note lock — safe under concurrent appends. not_found if the note is missing. 1 MiB cap on the resulting body (too_large).
postit.overwrite — name (required), content (required), dir?. Replaces the note's entire body with content (atomic write; the previous body is discarded). Use postit.append when you want to add to the body instead of replacing it. not_found if missing. 1 MiB cap on the new body (too_large).
These were a single postit.update_body tool with a mode flag in earlier releases. The flag did not translate cleanly to LLM tool use — agents would drop or mis-pick the mode and silently clobber a note — so it was split into two distinct tools with no shared argument.
postit.rename — name (required), new_name (required), dir?. Renames within the same directory. no_op if new_name == name; already_exists if the target is there. Same-dir only.
postit.delete — name (required), dir?. Removes the file. The directory is left in place even if now empty. not_found if missing.
postit.read — name (required), dir?. Returns {name, dir, body, mtime, size}. not_found if missing. For large bodies prefer read_section or read_lines.
postit.read_section — name (required), heading (required, case-insensitive exact text match), level? (1–6, default 2), dir?. Returns the matched heading line plus everything under it until the next heading of level ≤ level or EOF — i.e. the section and all its subheaders, verbatim. null if no heading matches. Match is exact text, not substring: read_section("auth") matches Auth but not Authorization.
postit.read_lines — name (required), start (1-based, required), end (1-based inclusive, required), dir?. Returns {name, dir, start, end, total_lines, lines} — body lines start..end inclusive. invalid_range if start < 1 or end < start. end beyond EOF is silently clamped; the returned end reflects the actual last line.

High-level tools

postit.ls — dir? (defaults to root), name?, recursive? (default false, dir mode only).
- Dir mode (name absent): a flat ls -la-style list of items in dir, dirs and postits interleaved alphabetically. Each dir item reports whether it has a TOPIC.md and a short preview of its description; each postit item reports mtime and size. With recursive=true, the whole subtree is walked into one flat list with full relative paths as the name, sort key = full relative path.
- Note mode (name set): {name, dir, total_lines, headings} — the Markdown headings in that file (level, text, 1-based line number), document order, no body content. Useful as a table of contents before read_section / read_lines. recursive ignored.
- TOPIC.md is never listed. Foreign files (non-.md) are ignored.
postit.search — pattern (Python re regex), scope ("name" | "body" | "both", default "both"), dir? (defaults to root), recursive? (default true), limit? (default 50). Walks the subtree, applies re.search case-insensitively (embed (?-i) to make it case-sensitive). Returns one entry per hit with full matching lines (grep-like), line numbers, and a flag for whether the name itself matched. Caps at limit. Skips TOPIC.md.
postit.recent — limit? (default 10), dir? (defaults to root). Walks the subtree rooted at dir (always recursive — no opt-out), sorts by mtime descending with path ascending as tiebreaker, returns the top limit as {path, name, mtime, size} with no body. Default dir=root returns every postit across the whole tree. Use at session start to reload context — body is deliberately not included.
postit.capabilities — no args. Read-only summary of what this server can execute: returns {server_name, server_version, store_root, tool_count, tools[]} where each tools[] entry is {name, title, read_only, destructive, idempotent, open_world} — the per-tool ToolAnnotations flattened. It is a lighter view than tools/list (no input schemas) and pins a stable shape the client can diff across versions. It does not report per-caller grants: which tools this caller may invoke is governed client-side by the editor's profile config (Zed: tool_permissions + per-profile context_servers.<server>.tools). The server has no caller identity (no auth on any transport) and so cannot honestly echo any caller's grant set; the probe reports the server's own surface only. Safe to call at session start alongside postit.recent.

'Hello World' notes for an agent that doesn't know where to start

At session start: call postit.recent with no args to see what you noted last, and postit.capabilities to pin the surface you're talking to (server name/version/store_root + the full registered tool list with effect hints). Optional: postit.ls the root or a project topic to see what topics exist.
Want to peek at a note without pulling the whole body? postit.ls with name set gives you the table of contents; then read_section for the part you care about, or read_lines for an exact range.
Lost a note? postit.search with a regex over names and bodies, recursive from root.
Filing things: topic.create first (top-down), then postit.create into it. Root / is fine for things that don't belong anywhere yet.

Errors

Errors are returned, not raised, as {code, message} objects. Codes:

dir_exists, dir_missing, already_exists, not_found, no_op
reserved_name, invalid_name, invalid_path, invalid_range
too_large (body write exceeds 1 MiB)

Extras

Container Notes

The image bakes POSTIT_HOST=0.0.0.0 so podman's published-port proxy can reach the listener inside the container netns. Host exposure is governed by the -p 127.0.0.1:8000:8000 publish flag on the run command — two distinct layers, do not conflate them.
There is no USER clause in the Dockerfile. Under rootless podman the in-container uid 0 maps to the invoking user's host uid, so bind-mounted ~/.agent-postit is readable and writable as your files with no chown or --userns ceremony. Under system podman / docker (where container root is real root), pass --user $(id -u):$(id -g) so files land as your uid.
Final image size is ~160 MB (python:3.12-slim-bookworm base plus the mcp dependency tree).
HEALTHCHECK runs every 30 s against http://127.0.0.1:8000/healthz (probed inside the container netns, where the server is reachable on loopback) using urllib from the base image. If you change the listen port, override POSTIT_PORT and the EXPOSE/-p mapping together.

Environment Variables

Env precedence (highest first): --root > POSTIT_ROOT > ~/.agent-postit. Same shape for transport / host / port: --transport > POSTIT_TRANSPORT

http; --host > POSTIT_HOST > 127.0.0.1; --port > POSTIT_PORT 8000. POSTIT_LOG (default -/stderr) has no CLI flag — see uv run python -m agent_postit --help for the full surface.

A second instance trying to bind the same loopback port exits cleanly with a "agent-postit already running on ..." message — the binary does a preflight TCP connect check before uvicorn starts, so there is no EADDRINUSE traceback and no need for a lock file.

Editor integration

Zed

Zed reads MCP server config from its settings file (open with zed: open settings file, or edit from Settings → AI → MCP Servers). HTTP servers live under context_servers with a url. The server must already be running — Zed does not spawn it.

If you run the agent in Zed's ask profile, make sure the postit write/mutate tools are explicitly enabled for that profile (under agent.profiles.<name>.context_servers.agent-postit.tools) and that tool_permissions does not block them. A misconfigured profile can look identical to a server bug — silent permission denials, no error on the server side. Thee server itself has no auth and no awareness of which profile is calling; everything is a client-side permission question.

{
    "context_servers": {
        "agent-postit": {
            "url": "http://127.0.0.1:8000/mcp",
        },
    },
}

Verify the server is live. In Zed open Settings → AI → MCP Servers and watch the indicator dot next to agent-postit. Green with the tooltip "Server is active" means the handshake succeeded and the 15 tools have been registered. Red indicates an error; hover for details (typically the server process is not running, or the port is wrong). A quick independent check: curl -s http://127.0.0.1:8000/healthz.

If you bounce the server (rebuild, restart the container, etc.), Zed will hold a stale session id — reload the MCP server from that same MCP Servers pane to re-handshake.

No Authorization header is required by the server. If a client insists on sending one (some do), a dummy Authorization: Bearer x is ignored — it is cosmetic, not enforced.

Tool permissions (Zed)

By default Zed prompts before every tool call. Per-tool entries use the mcp:<server>:<tool> key and override the global agent.tool_permissions.default. Anything not listed inherits that default.

For the full reference see the Zed MCP guide and the tool permissions doc.

{
    "agent": {
        "tool_permissions": {
            "tools": {
                // agent-postit: auto-allow
                "mcp:agent-postit:topic.read": { "default": "allow" },
                "mcp:agent-postit:postit.read": { "default": "allow" },
                "mcp:agent-postit:postit.read_section": { "default": "allow" },
                "mcp:agent-postit:postit.read_lines": { "default": "allow" },
                "mcp:agent-postit:postit.ls": { "default": "allow" },
                "mcp:agent-postit:postit.search": { "default": "allow" },
                "mcp:agent-postit:postit.recent": { "default": "allow" },
                "mcp:agent-postit:topic.create": { "default": "allow" },
                "mcp:agent-postit:topic.write": { "default": "allow" },
                "mcp:agent-postit:postit.create": { "default": "allow" },
                "mcp:agent-postit:postit.capabilities": { "default": "allow" },

                // agent-postit: confirm first
                "mcp:agent-postit:postit.append": { "default": "confirm" },
                "mcp:agent-postit:postit.overwrite": { "default": "confirm" },
                "mcp:agent-postit:postit.rename": { "default": "confirm" },
                "mcp:agent-postit:postit.delete": { "default": "confirm" },
            },
        },
    },
}

stdio fallback

--transport stdio (POSTIT_TRANSPORT=stdio) makes the binary speak JSON-RPC over stdin/stdout instead of binding a port. It is kept for one-off sessions against a temp root and for environments without a service manager where the client spawns the server as a child process:

uv run python -m agent_postit --transport stdio --root /tmp/scratch-notes

stdio and HTTP are not bridgeable. They are two different code paths in the same binary: stdio uses the SDK's stdio transport and writes one JSON-RPC frame per line; HTTP uses the Streamable HTTP transport and a long-lived server. There is no --transport bridge and no plan to add one — pick the transport that matches how your client speaks MCP. HTTP is the default and the one you want for dogfooding.

License

MIT.

Available Tools

13 tools

postit.createC

Create a new postit note.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.8/5.0

Behavior2/5

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 only states the action without mentioning side effects, return values, permissions, or error conditions. For a create operation, important behavioral details are absent.

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 succinct sentence with no redundant words. It is effectively concise, though it lacks structural detail. The brevity is acceptable but does not provide added value beyond a minimal statement.

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?

The tool has multiple parameters and an output schema, yet the description provides no context about parameter semantics, usage scenarios, or expected behavior. The presence of an output schema mitigates the need to explain return values, but the description remains insufficiently complete for an agent to invoke it correctly without additional guessing.

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

Parameters1/5

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

The input schema has three properties (name, body, dir) but the description provides zero parameter information. With schema description coverage at 0%, the description was expected to compensate, but it mentions none of the parameters or their meanings.

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 'Create a new postit note' uses a specific verb ('Create') and a clear resource ('postit note'), distinguishing it from sibling tools like postit.rename or postit.delete. It is direct and unambiguous, fulfilling the purpose clarity criterion.

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 provides no guidance on when to use this tool versus alternatives such as topic.create or other postit operations. It lacks context about prerequisites, exclusions, or scenarios where a different tool would be more appropriate.

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

postit.deleteA

Delete a postit note (dir survives).

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

The description discloses the core destructive behavior (deletes a note) and adds one useful nuance: the directory survives. However, with no annotations, it omits other potentially relevant behaviors such as irreversibility, permission requirements, or response details.

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 a single concise sentence with a clarifying parenthetical. Every word adds value and there is no redundancy.

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?

For a simple delete tool, the description is minimally adequate but leaves gaps in parameter semantics and usage guidance. Output schema exists, which may explain return values, but the description alone does not fully cover context.

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 and the description itself barely explains parameters. 'Name' is implied as the note identifier, and 'dir survives' gives some hint about the dir parameter, but neither is formally explained.

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 clearly states the tool deletes a postit note, using a specific verb and resource. It distinguishes itself from siblings as the only delete operation, with the parenthetical clarifying scope (directory survives).

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

Usage Guidelines4/5

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

The intended use is clear: delete a postit note. There are no alternative delete tools among siblings, so explicit alternatives are unnecessary. The parenthetical provides context about directory behavior, which helps the agent decide when to use this tool.

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

postit.lsA

List dir contents (ls -la style) or list headings of one postit.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are present, so the description must disclose behavioral traits. It only mentions the listing modes and style, but fails to state that the operation is read-only, how invalid inputs or parameter combinations are handled, or whether recursion applies to both modes. This leaves significant behavioral uncertainty.

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 a single, concise sentence with no redundant words. It leads with the verb and clearly lists the two modes, making it highly readable and appropriately front-loaded.

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?

While an output schema exists, the tool has three undocumented parameters and no annotations. The description fails to explain how to set up the parameters for each mode or what happens when both dir and name are provided. It is not complete enough for reliable invocation.

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. It hints that 'dir' maps to directory listing and 'name' to headings, but does not explain the 'recursive' parameter, parameter precedence, or expected formats. The compensation is minimal and incomplete.

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 action ('List') with two clear targets: dir contents in 'ls -la style' and headings of a postit. This clearly distinguishes it from sibling tools like postit.read (full content), postit.read_lines (specific lines), and postit.read_section (sections).

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

Usage Guidelines4/5

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

The description defines two explicit use cases—directory listing and heading listing—making it clear when to invoke this tool. It does not explicitly name alternatives or state exclusions, but the context implies the appropriate scenarios.

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

postit.readC

Read a postit's full body.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

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 only says 'Read', which conveys a read-only operation, but does not describe what constitutes the 'full body', how the optional 'dir' parameter affects behavior, error handling, or return format. The output schema exists but the description adds no extra 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.

Conciseness5/5

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

The description is a single, front-loaded sentence with no unnecessary words. It states the core purpose efficiently and earns its place without redundancy.

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?

Although an output schema exists and sibling tools provide some context, the description omits crucial usage context: when to use this vs. read_section/read_lines, how 'dir' factors in, and what 'full body' means (including formatting or size limits). The tool is simple, but the description alone is insufficient for an agent to confidently invoke it.

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

Parameters1/5

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

Schema description coverage is 0%—the description does not mention the required 'name' parameter or the optional 'dir' parameter. Since the description must compensate for the schema's lack of semantic detail but fails to do so, the parameter semantics are effectively absent.

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 'Read a postit's full body' clearly states the verb (read) and resource (postit), and the 'full body' scope distinguishes it from sibling tools like postit.read_section and postit.read_lines. It is concise and unambiguous, though it does not elaborate on what a 'postit' is in this domain.

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 phrase 'full body' implies this tool is for reading the complete content of a postit, as opposed to partial reads (read_section, read_lines) or listing (postit.ls). However, it does not explicitly state when to prefer this over alternatives or provide any exclusions, so usage guidance is only implied.

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

postit.read_linesA

Read a 1-based inclusive line range from a postit body.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/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 adds useful context about 1-based inclusive indexing, but it does not disclose behavior for invalid line numbers, missing postits, or edge cases like out-of-range start/end. The 'dir' parameter's effect on lookup is also unexplained.

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 a single sentence that immediately states the action and key constraint ('1-based inclusive'), with no filler or redundancy.

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?

The tool is relatively simple, but the description leaves parameter semantics and error behavior unaddressed. The output schema exists, so return values are covered, but with no annotations and four parameters, a bit more context would improve completeness.

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 only clarifies that start and end are a 1-based inclusive range. It does not explain what 'name' refers to, what 'dir' does, or how they relate to locating the postit. This fails to compensate for the lack of schema-level descriptions.

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 clearly states the action ('Read'), the resource ('a postit body'), and the specific scope ('1-based inclusive line range'). This distinguishes it from siblings like postit.read (full content) and postit.read_section (sections).

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 implies usage when needing a specific line range, but it does not explicitly discuss when to use it versus alternatives like postit.read or postit.read_section. No exclusions or prerequisites are mentioned.

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

postit.read_sectionA

Read a markdown section by heading text (case-insensitive, exact).

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior4/5

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

With no annotations, the description carries the full burden of safety and behavior. It usefully discloses the matching rule (case-insensitive, exact), but does not explain what happens if no heading matches, if multiple match, or whether subheadings are included. Still, it adds meaningful behavioral context beyond what the schema provides.

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 a single, front-loaded sentence with no filler. Every word adds value by specifying the action, resource, and matching exactness.

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?

The tool has a nested requirement (name and heading are required), an output schema, and no annotations, yet the description is minimal. It omits critical parameter meanings (name, level, dir) and does not explain the return format or edge cases. Sibling tools exist but no comparison is provided, making it incomplete for correct invocation.

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 by explaining parameters. It only clarifies the 'heading' matching semantics. The required 'name' parameter and optional 'level' and 'dir' parameters are not mentioned, leaving the agent to guess how to specify which document and heading level to target.

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 uses the specific verb 'Read' and identifies the resource as 'markdown section', with clear matching criteria (heading text, case-insensitive, exact). This distinguishes it from sibling read tools like postit.read or postit.read_lines, which presumably read the whole note or lines.

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 implies when to use this tool (read a specific section by heading) but provides no explicit guidance on when not to use it or how it compares to alternatives like postit.read, postit.read_lines, or postit.search. It lacks exclusions or named alternatives.

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

postit.recentB

Return most-recently-modified postits (always recursive under dir).

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior3/5

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

With no annotations, the description carries the transparency burden. It discloses the recursive traversal and recency-based ordering ('most-recently-modified'), but it does not mention limit semantics, default directory behavior, or explicitly confirm read-only status. This is partial but not complete transparency.

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 a single, front-loaded sentence with no filler or repetition. It efficiently conveys the core purpose and a key behavioral detail.

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?

The output schema likely documents return values, and the description covers the primary retrieval purpose and recursive scope. However, it lacks usage context and parameter details, making it minimally viable rather than fully complete for an agent deciding how to invoke it.

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. It gives context for 'dir' by saying 'under dir,' but the 'limit' parameter is entirely unexplained, including its meaning or default behavior. Only one of the two parameters receives any semantic clarification.

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 clearly states the tool returns 'most-recently-modified postits' and includes the scope 'always recursive under dir,' which distinguishes it from sibling listing tools like postit.ls and postit.read. The verb 'Return' and resource 'postits' make the operation unambiguous.

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 choose this tool over alternatives like postit.ls or postit.search. The phrase 'always recursive under dir' describes behavior but not the intended use case or exclusions.

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

postit.renameB

Rename a postit within the same dir.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the basic action and the 'same dir' constraint, omitting crucial details such as error handling (e.g., what if the postit does not exist), whether the operation overwrites an existing name, permission requirements, or any side effects. This is insufficient for a mutating tool with zero annotation context.

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, front-loaded sentence without redundancy, which is efficient. However, its brevity borders on under-specification, missing useful parameter or behavioral context that would aid the agent. It earns its place but could be enriched without becoming verbose.

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?

Given the tool has three parameters, no annotations, and only an output schema (which helps with return values), the description covers the core operation but leaves out parameter semantics, possible error conditions, and the exact implications of 'same dir'. The description alone is insufficient for a fully informed invocation in a complex context.

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. It references 'same dir' which loosely maps to the 'dir' parameter, but it does not explain the optional/default behavior of 'dir' nor clarify the roles of 'name' and 'new_name' beyond what their names imply. The lack of explicit parameter details leaves room for ambiguity.

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 clearly states the action ('Rename') and resource ('a postit') and adds a scope constraint ('within the same dir'), which distinguishes it from siblings like postit.create, postit.delete, or postit.update_body. The verb-resource pair is specific and unambiguous.

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

Usage Guidelines4/5

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

The description implies when to use the tool: to rename a postit while keeping it in the same directory. The 'same dir' clause sets a clear limitation, but it does not explicitly mention alternatives or when not to use, such as for moving between directories. Without explicit exclusions, it falls short of a 5.

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

postit.searchA

Regex search across postit names and/or bodies (grep-like).

ParametersJSON Schema

Name	Required	Description	Default
`arg`	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?

No annotations are provided, so the description carries the full burden. It conveys that this is a read-only regex search and adds the 'grep-like' trait, but it does not disclose behavior around directory scoping, recursion, result limiting, or output format. The description is minimal but not misleading.

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 a single sentence, front-loaded with the core action 'Regex search'. Every word contributes meaning, with no filler or redundant information. It is appropriately sized for the tool's simplicity.

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 five parameters and no annotations, a one-sentence description is thin. It covers the core purpose but omits context about directory targeting, recursion defaults, and result handling. The presence of an output schema mitigates some ambiguity about return values, but the description still lacks depth for a multi-parameter tool.

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?

The schema has zero descriptions for its fields, so the description must compensate. It clarifies that 'pattern' is a regex and that 'scope' covers names and/or bodies, but it does not explain 'dir', 'limit', or 'recursive', leaving those to be interpreted from their names and defaults.

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 clearly states the specific verb 'search' and the resource 'postit names and/or bodies', further clarified by 'grep-like' to indicate regex matching. This distinguishes it from sibling read/list tools such as postit.read or postit.ls.

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 implies usage for regex-based search across postit fields but provides no explicit guidance on when to choose this tool over siblings, nor any exclusions or alternative recommendations. The use case is inferred from the verb 'search'.

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

postit.update_bodyB

Append or overwrite a postit's body.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

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

Annotations are absent, so the description must fully disclose behavior. It only states the operation type (append/overwrite) but provides no details on consequences such as whether append adds to the end, whether overwrite replaces entirely, what happens if the postit does not exist, or any permission requirements. This is a significant gap for a mutation 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 a single, front-loaded sentence with no fluff. It efficiently conveys the core action, making it easy to parse. It is appropriately sized for the tool's simplicity, though it sacrifices detail.

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?

Given the moderate complexity (nested object, 4 parameters, no annotations, 0% schema description coverage), the description is far from complete. It omits critical parameter context (dir, name, mode default) and behavioral edge cases. The presence of an output schema helps with return values, but the tool remains under-specified for reliable agent usage.

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 parameter meanings. It only implies 'content' as the body and 'append/overwrite' as the mode, but fails to explain 'name' as identifier, the optional 'dir', or the default mode. The description adds marginal semantic value beyond the schema's raw fields.

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 clearly states the tool's function: appending or overwriting a postit's body. The verb 'append/overwrite' plus resource 'postit's body' is specific and distinguishes it from siblings like postit.read, postit.rename, and postit.delete.

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 implies usage for modifying an existing postit's content, but does not explicitly state when to use it versus alternatives like postit.create or postit.rename. No exclusions or alternative references are provided, leaving the agent to infer 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.

topic.createB

Create a topic dir + TOPIC.md description.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It states that it creates a directory and a TOPIC.md file, but does not disclose what happens if the directory already exists, whether it overwrites content, or any permission requirements. This is a minimal, surface-level description that lacks side-effect and safety details.

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 a single, front-loaded sentence that conveys the core action and outputs without unnecessary words. Every word earns its place, making it compact and easily parseable.

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?

Given the lack of annotations, an output schema that is not shown, and zero schema descriptions, the description is insufficient for an agent to reliably invoke the tool. It does not specify what 'dir' should look like (e.g., path vs. name), whether 'description' is the entire file content, or what the tool returns. A simple creation tool still needs more contextual guidance for correct usage.

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 schema provides no descriptions (0% coverage) and the parameters are wrapped in a single 'arg' object. The description hints that 'dir' is the directory name and 'description' is the content for TOPIC.md, but it does not explicitly map parameters, nor does it explain input formats, constraints, or relationships. The description only partially compensates for the lack of schema detail.

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 uses a specific verb ('create') and a concrete resource ('topic dir + TOPIC.md description'), clearly stating what the tool produces. It distinguishes from sibling tools like postit.create by focusing on topic-specific content, and the mention of TOPIC.md makes the purpose unambiguous.

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 explicit guidance on when to use this tool versus alternatives like topic.write or postit.create. It does not mention prerequisites (e.g., whether the topic directory must not already exist) or any context in which this tool is appropriate. The name implies creation, but the description itself offers no usage direction.

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

topic.readB

Read a topic's TOPIC.md description.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior3/5

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

As a read operation, the core behavior is safe and non-destructive, which is implied by the verb. However, with no annotations, the description carries the full burden and does not disclose potential error conditions, whether it returns raw file content, or any special handling of the TOPIC.md file. It is adequate but lacks depth.

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 a single sentence, six words, with no filler or redundancy. It is front-loaded and appropriately sized for the simple operation it describes.

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?

The tool has one parameter with zero semantic explanation, and the description does not provide context about what constitutes a 'topic' or how 'dir' is interpreted. While an output schema exists (covering return values), the missing parameter semantics and lack of usage context leave the tool incomplete for an agent to invoke reliably.

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

Parameters1/5

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

The only parameter, 'dir', is completely undocumented in both the schema (0% coverage) and the description. The description does not hint at what 'dir' represents (e.g., a filesystem path, a topic identifier, or a workspace). This is a critical gap for correct usage.

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 clearly states the verb 'Read' and the resource 'a topic's TOPIC.md description', providing a specific and unambiguous purpose. It distinguishes from sibling tools like topic.write and postit.read by naming the exact file and operation.

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 indication of when to use this tool versus alternatives such as topic.create or postit.read. There is no mention of context, prerequisites, or exclusions, leaving the agent without strategic guidance.

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

topic.writeB

Overwrite a topic's TOPIC.md description.

ParametersJSON Schema

Name	Required	Description	Default
`arg`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

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

With no annotations, the description must carry full behavioral disclosure. It reveals that the tool overwrites a description, but does not mention any side effects, permission requirements, or whether the operation is destructive to other parts of the topic file.

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 a single, front-loaded sentence with no filler. It states exactly what the tool does, earning every word.

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?

The tool has no annotations and minimal description, leaving the agent without information about how to specify the topic, whether the operation is safe, or what the output contains (though output schema exists). More context is needed for reliable invocation.

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 explain the parameters. Although 'dir' and 'description' are intuitively named, the nested structure and exact meaning are left unclear, so the description adds little semantic value.

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 uses a specific verb ('Overwrite') and names the resource ('a topic's TOPIC.md description'), clearly distinguishing it from sibling tools like topic.create and topic.read.

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 provided on when to use this tool vs. alternatives. While the verb 'overwrite' implies updating an existing topic, there is no explicit context, prerequisites, or exclusions.

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. Dates show when Glama detected each change.

13 tool updatesv0.1.0Aug 2, 2026
- First observedpostit.create
- First observedpostit.delete
- First observedpostit.ls
- First observedpostit.read
- First observedpostit.read_lines
- First observedpostit.read_section
- First observedpostit.recent
- First observedpostit.rename
- First observedpostit.search
- First observedpostit.update_body
- First observedtopic.create
- First observedtopic.read
- First observedtopic.write

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Each tool targets a distinct resource and operation: topics have create/read/write, postits have create/read/update/delete/rename/list/search/recent, with read subdivided into full, section, and line-range variants that are clearly differentiated. No two tools overlap in purpose.

Naming Consistency4/5

Tool names follow a consistent dot-separated resource.action pattern (e.g., topic.create, postit.read_section), but there are minor deviations: 'ls' is an abbreviation rather than a verb, 'recent' is not a verb, and 'update_body' contrasts with 'write' for topics.

Tool Count5/5

With 13 tools, the set is well-scoped for a note/topic management server. Each tool provides a distinct capability, and the count is within the ideal range—neither too sparse nor overwhelmingly large.

Completeness4/5

The postit lifecycle is fully covered (create, read, update, delete, rename, list, search, recent), and topics have create/read/write. Notable gaps include no topic delete or rename, and postit rename is restricted to the same directory, preventing moves. These are minor but slightly limit full lifecycle management.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

hjarni AOAuth
com.hjarni
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Note Taking Workplace & Productivity
3
cortexpad A
com.cortexpad
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Note Taking Knowledge & Memory
162
Agentage MemoryOAuth
io.agentage
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge & Memory File Systems
2
TaprootOAuth
com.taproothq
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Knowledge & Memory Note Taking
2

Related MCP Servers

genmem
Knowledge & Memory Note Taking
helloSobuj
A
license
Not graded
quality
C
maintenance
A local-first MCP server that gives AI assistants long-term memory by storing, searching, and recalling notes as Markdown files on your machine.
Updated 3 months ago (2026-06-11 09:08 UTC)
14
MIT
basic-memory-mcp
Note Taking Knowledge & Memory File Systems
garland3
A
license
A
quality
B
maintenance
An MCP server that gives AI models a persistent notebook backed by a folder of Markdown files, with tools to discover, read, write, edit, and delete notes.
Updated 11 days ago (2026-08-26 23:10 UTC)
9
MIT
edumem-mcp
Knowledge & Memory File Systems Note Taking
SkillfulElectro
A
license
Not graded
quality
C
maintenance
An MCP server that gives LLM agents persistent, directory-scoped memory using markdown files, supporting workspace-specific notes and read-only shared memories.
Updated a month ago (2026-08-07 20:23 UTC)
MIT
vault-mcp
Knowledge & Memory Note Taking
seandavi
A
license
A
quality
B
maintenance
MCP server that exposes an Obsidian-style markdown vault as a shared memory for AI agents, with tools for searching, reading, writing, and querying notes and wiki-links.
Updated a month ago (2026-08-08 10:48 UTC)
12
3
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gerelef/agent-postit'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Topic Management

Note (Postit) CRUD

Partial Reading

Discovery & Search

Introspection

agent-postit

Build, install, run

Container (podman or docker)

Building from source (optional)

Under systemd --user (rootless quadlet)

Tools

Topic tools

Postit CRUD

High-level tools

'Hello World' notes for an agent that doesn't know where to start

Errors

Extras

Container Notes

Environment Variables

Editor integration

Zed

Tool permissions (Zed)

stdio fallback

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Under `systemd --user` (rootless quadlet)