Allows browsing and curating posts from hand-picked Instagram tattoo artists via Instagram's Business Discovery API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Tattoo Feed Show me my saved inspirations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that lets an LLM client (e.g. Claude Desktop) browse and curate posts from a hand-picked list of Instagram tattoo artists, via Instagram's Business Discovery API.
You point it at the artists you follow, and from your chat client you can pull a merged feed, discover one post at a time, bookmark the ones you like, and record notes about your taste so a future session remembers them.
A deliberate two-layer split so a future GUI can reuse the logic without a rewrite:
core (src/tattoo_feed/ excluding server/) — all real logic: domain
models, typed errors, JSON-file repositories, the Graph API client, image
processing, and the services that orchestrate them. Knows nothing about MCP.
server (src/tattoo_feed/server/) — a thin FastMCP
adapter that exposes core as MCP tools. Holds no business logic.
src/tattoo_feed/
config.py # lazy env config (IG_ACCESS_TOKEN, IG_USER_ID)
models.py # Pydantic v2 value objects
errors.py # typed error hierarchy
imaging.py # preview downscale + EXIF strip
repositories/ # Repository ABC + JSON-file stores (atomic writes)
graph/client.py # Business Discovery client
services/ # FeedService, ArtistService, InspirationService, PreferenceService
server/app.py # FastMCP tools + stdio entrypointRelated MCP server: instagram-personal-mcp
Requirements: Python 3.12 and uv.
uv sync # create the venv and install pinned deps
cp .env.example .env # then edit .env with your real credentialsVariable | Meaning |
| A long-lived Instagram Graph API access token. |
| The Instagram Business/Creator account id that owns the token. |
| Optional. Where the JSON stores live (default |
.env is gitignored and must never be committed. Only .env.example (with
placeholders) is in the repo.
Getting credentials is a one-time manual step on Meta's side: create a Meta app, connect an Instagram Business/Creator account, and mint a long-lived access token with Business Discovery permission. Both the querying account and the artists you look up must be professional accounts.
uv run python -m tattoo_feed.server.appThe server speaks the MCP stdio protocol, so you normally don't run it by hand — you register it with an MCP client. For Claude Desktop, add to its config:
{
"mcpServers": {
"tattoo-feed": {
"command": "uv",
"args": ["run", "python", "-m", "tattoo_feed.server.app"],
"cwd": "/absolute/path/to/tattoo-feed",
"env": {
"IG_ACCESS_TOKEN": "your-token",
"IG_USER_ID": "your-business-user-id"
}
}
}
}A dev image (Dockerfile) bundles Python, uv, Node, and the toolchain. Build
and open a shell with only this folder mounted to /workspace:
docker build -t tattoo-feed-dev .
./run-loop.sh # mounts $PWD to /workspace, nothing else on your machineInside the container you have the full gate and can run the server exactly as
above. The volume mount means anything written under /workspace lands back in
this folder on your host.
Tool | What it does |
| List tracked artists. |
| Validate the handle is a reachable professional account, then track it. |
| Stop tracking a handle. |
| Merged, newest-first feed. Metadata + permalinks only (no images). |
| One not-yet-seen post, marked seen, with a rendered preview image. |
| Bookmark a post into the saved collection. |
| The saved collection, in save order. |
| Remove a saved item. |
| Clear the seen-set so inspiration starts fresh. |
| Persist a taste note (propose-then-confirm, see below). |
| All recorded preferences, to reload taste in a fresh session. |
Two-layer split (core / server). MCP concepts never leak into core;
business logic never leaks into server. This is what makes a phase-2 GUI a
bolt-on rather than a rewrite.
JSON-file persistence behind a Repository interface. Simple, inspectable,
and swappable. Writes are atomic (temp file + os.replace) so a crash
mid-write can never corrupt a store.
Pydantic v2 frozen models for everything crossing a boundary, so external data is validated once and treated as immutable values thereafter.
Typed error hierarchy (TattooFeedError and friends). Every external
failure maps to a typed error; nothing raises bare exceptions across a
boundary, so the client always gets a readable message instead of a stack
trace.
Lazy credentials. The server boots and lists its tools with no network and no real credentials; the token is only read when a tool actually calls Instagram.
Hermetic tests. All Instagram HTTP is mocked with respx; there are zero
live network calls in the test suite. (mypy --strict, ruff, and a 90%
coverage floor are enforced.)
Images only where they earn their context. Only next_inspiration returns
a rendered image — the one-at-a-time conversational moment. get_feed stays
metadata-only to keep the context window light.
No video. Video posts are filtered out entirely at the Graph-client layer and never enter the feed, inspiration, or stores.
Carousels show the first image only. Multi-image expansion is out of scope.
Manual token refresh. There is no automatic token refresh. When the token
expires, tools fail with a clear TokenExpiredError telling you to mint a new
long-lived token and update IG_ACCESS_TOKEN.
Preview sizing is fixed. Previews are capped at 640px on the long edge, aspect ratio preserved, never upscaled, re-encoded as JPEG quality 85.
record_preference is propose-then-confirm. The tool persists whatever it
is given; the discipline of proposing the observation to you and getting your
explicit confirmation before the tool is called lives in the tool's
description, so the calling assistant honours it.
No write access to Instagram. No posting, commenting, or messaging — this is strictly read-and-curate.
Posts belong to the artists who made them. This tool is for personal discovery and curation, not redistribution:
Previews are downscaled copies (≤640px, EXIF stripped), not full-resolution downloads.
Every image and saved item carries the artist's handle and the post's permalink, so attribution travels with the content and you can always open the original on Instagram.
Respect each artist's rights: don't repost or reuse their work without permission.
The full gate (must all exit 0):
uv run ruff format --check .
uv run ruff check .
uv run mypy --strict src
uv run pytest -q --cov=src/tattoo_feed --cov-report=term-missing --cov-fail-under=90MIT — see LICENSE.
Track a new artist by Instagram handle.
The handle must resolve to a reachable professional (Business/Creator) account; otherwise a clear error is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes |
| Name | Required | Description |
|---|---|---|
| handle | Yes | |
| ig_user_id | No | |
| added_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses the handle validation requirement and error clarity, but omits other behavioral traits such as duplicate handling, permissions needed, or side effects. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no redundant words, and all information is relevant. The key constraint is front-loaded in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers the core purpose and a critical constraint. It does not explain return values (covered by output schema) or behavior for duplicate entries, but remains mostly complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single parameter 'handle', and the description only adds that it is an 'Instagram handle' without specifying format (e.g., with/without @). This provides minimal additional meaning beyond the schema's title 'Handle'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Track a new artist') and the resource ('by Instagram handle'). This distinguishes it from sibling tools like 'remove_artist' or 'list_artists', which involve different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: the handle must resolve to a professional (Business/Creator) account, and explicitly states the error behavior for invalid handles. It implicitly guides when to use (when adding a new artist after verifying the handle), but does not mention when not to use or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent posts from all tracked artists, newest first.
Returns metadata and permalinks only (no images) to keep context light.
| Name | Required | Description | Default |
|---|---|---|---|
| limit_per_artist | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that only metadata and permalinks are returned (no images) and that results are sorted newest first. This is useful behavioral context, though it doesn't mention pagination or rate limits. No contradictions with annotations (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each essential. The first states the core purpose, the second adds an important qualifier about return content. No wasted words, front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description covers the main function and return limitations. However, it omits explanation of the parameter, which is a clear gap. The output schema likely covers return values, so that is not a deficiency here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the single parameter 'limit_per_artist'. The tool description does not mention or explain this parameter at all, leaving the agent with no meaning beyond the default value and type. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns recent posts from all tracked artists, newest first. It specifies the resource (recent posts), verb (return), and scope (all tracked artists), which distinguishes it from sibling tools that manage artists or inspiration lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or any prerequisites (e.g., artists must be tracked first). The description lacks explicit usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return every recorded taste preference, so a fresh session can reload it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description clearly indicates a read operation returning all preferences. It does not disclose any additional behavioral traits, but for a simple retrieval tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and to the point. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, low complexity, and an existing output schema, the description is complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the schema coverage is 100%. The description does not need to add parameter info; baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every recorded taste preference, with a specific verb 'Return' and resource 'every recorded taste preference'. It distinguishes from siblings like record_preference which records new preferences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context ('so a fresh session can reload it') indicating when to use: at session start to reload preferences. It does not explicitly mention alternatives or when not to use, but the purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tattoo artists currently being tracked.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the list is of 'currently being tracked' artists, but does not disclose whether it is read-only, requires authentication, or any other behavioral traits. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff. Perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema provided, the description need not explain return values. It fully captures what the tool does—list all tracked artists—which is sufficient for a zero-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. Per guidance, baseline for 0 parameters is 4. The description does not need to add parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'tattoo artists currently being tracked', which is specific and distinguishes from siblings like add_artist (adding) and remove_artist (removing). No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a simple list operation but provides no explicit guidance on when to use this tool versus siblings like get_feed or list_inspiration. Adequate but lacks context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved inspiration items, in the order they were saved.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions ordering, which is behavioral, but lacks details on number of items, pagination, or potential side effects. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no wasted words. Front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers basic purpose, it omits details like return structure (despite output schema existing), pagination, and error handling. Adequate for a simple list but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline is 4 for 0 parameters; the description adds no param info but is not needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'list', the resource 'saved inspiration items', and an ordering detail 'in the order they were saved', distinguishing it from siblings like save_to_inspiration or remove_from_inspiration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., next_inspiration, list_artists) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show one not-yet-seen post for inspiration, then mark it seen.
Returns a rendered preview image (downscaled, EXIF-stripped) alongside the
artist handle and permalink. Calling repeatedly walks through unseen posts;
use reset_seen to start over.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that it marks the post as seen, returns a downscaled and EXIF-stripped preview, and that repeated calls walk through unseen posts. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the main action and purpose without extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, an output schema, and sibling tools listed, the description fully covers the tool's behavior, return value, and relationship to reset_seen. Complete for the available information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the baseline is 4. The description adds no parameter-specific information, which is acceptable given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows one not-yet-seen post, marks it seen, and returns a preview with artist handle and permalink. It distinguishes from siblings like reset_seen and list_inspiration by explaining the sequential browsing behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions using reset_seen to start over, and implies sequential use for walking through unseen posts. However, it does not comprehensively cover when not to use this tool or alternative contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a note about the user's tattoo taste.
IMPORTANT: Before calling this tool, propose the observation to the user in
your own words and obtain their explicit confirmation. Only call it once the
user has agreed the observation is accurate. This captures taste (e.g.
"prefers fine-line botanical work"), which is distinct from saving a
specific image with save_to_inspiration.
| Name | Required | Description | Default |
|---|---|---|---|
| observation | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| observation | Yes | |
| created_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool records a taste observation and requires user consent, which is important for a write operation. However, it does not mention any potential side effects (e.g., overwriting existing preferences), but it is concise enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. The critical instruction is bolded for emphasis. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and an existing output schema, the description fully covers when to use, what to capture, and the prerequisite step. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that the 'observation' parameter captures taste and provides an example ('prefers fine-line botanical work'), adding meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a note about the user's tattoo taste. It distinguishes itself from the sibling tool 'save_to_inspiration' which saves specific images, making 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to propose the observation to the user and obtain explicit confirmation before calling. This is a crucial prerequisite, and the description also clarifies when to use this tool versus saving an image, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop tracking the artist with the given handle.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It says 'stop tracking' but does not explain whether this is destructive, if it affects existing data, or requires special permissions. This is insufficient for a tool that likely performs a mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise and front-loaded, but it achieves conciseness at the expense of completeness. A bit more detail would not significantly harm conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, low schema coverage, and the presence of an output schema (not shown), the description is incomplete. It does not cover what happens upon removal, idempotency, or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The only parameter 'handle' has no description in the schema, and the tool description merely mentions 'given handle' without explaining its format, scope, or constraints. The description does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('stop tracking') and the resource ('artist with the given handle'). It is specific and distinguishes from sibling tools like 'add_artist' which performs the opposite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention usage context, prerequisites, or situations where other tools like 'list_artists' or 'get_feed' 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.
Remove a saved inspiration item by post id.
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It implies a destructive write operation ('Remove') but provides no details on side effects, required permissions, or whether the operation is reversible. The return value or confirmation is not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It front-loades the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and no annotations, the description omits critical context such as what the tool returns upon success, whether it errors on invalid id, or how it relates to sibling tools like 'save_to_inspiration' or 'list_inspiration'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds that the removal is 'by post id', confirming the parameter's purpose. However, it doesn't explain what 'post_id' refers to or where to obtain it, leaving ambiguity for an agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove'), the resource ('a saved inspiration item'), and the identifier ('by post id'). It distinguishes from siblings like 'save_to_inspiration' (opposite) and 'remove_artist' (different resource), but doesn't explicitly differentiate from 'reset_seen' or 'clear' operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool vs. alternatives (e.g., 'remove_artist' for artists, or 'reset_seen' for clearing seen state). No prerequisites or context for safe invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the seen-set so next_inspiration starts fresh.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a state-mutating operation ('clear') but provides no additional behavioral details such as side effects, reversibility, or permissions. With no annotations to rely on, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise, front-loaded, and contains no superfluous information. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with an output schema, the description is sufficiently complete. It explains the core action and effect. Minor improvement could be mentioning the output (e.g., confirmation).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. The description does not need to add parameter semantics, and it adequately explains the action. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: clearing the seen-set to reset the state for next_inspiration. It uses a specific verb ('clear') and resource ('seen-set'), and implicitly distinguishes from siblings like remove_from_inspiration and next_inspiration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies usage when a fresh start for next_inspiration is needed, it lacks explicit when-to-use or when-not-to-use guidance, and does not mention alternatives among siblings. Simple context but no directed advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bookmark a post (by id, from the current feed) into saved inspiration.
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ||
| notes | No |
| Name | Required | Description |
|---|---|---|
| post_id | Yes | |
| artist_handle | Yes | |
| image_url | Yes | |
| permalink | Yes | |
| timestamp | Yes | |
| notes | No | |
| saved_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states it bookmarks a post, implying a write operation, but lacks details on side effects, idempotency, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads the core action. Could be more concise by removing parenthetical 'by id, from the current feed', but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple function with 2 params and output schema, description covers the basic action but lacks details on return value, success/failure, or constraints. Adequate for a straightforward bookmarking tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. Only 'post id' is mentioned in description; 'notes' parameter is not explained. The description adds little beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Bookmark' and resource 'post', and distinguishes from siblings like 'remove_from_inspiration' and 'list_inspiration'. However, it does not explicitly differentiate from similar siblings like 'record_preference'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for bookmarking posts from the current feed, but no explicit when-to-use or when-not-to-use guidance. No mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools generally have distinct purposes, but 'get_feed' and 'next_inspiration' both involve browsing posts from tracked artists, with 'next_inspiration' showing one unseen post at a time while 'get_feed' returns all recent posts. This could confuse an agent about which to use for browsing.
All tool names follow a consistent verb_noun snake_case pattern, such as 'add_artist', 'list_inspiration', 'save_to_inspiration'. Even 'next_inspiration' with a non-standard verb is still in snake_case and fits the pattern.
With 11 tools, the server provides a well-scoped set for tracking artists, managing inspiration, and recording preferences. Each tool has a clear role without redundancy or excessive overlap.
The tool set covers core workflows: artist management (add/list/remove), feed browsing, inspiration management, and preference recording. However, there is no tool to delete or update a recorded preference, which is a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for QPost — lets AI agents publish video and image posts to YouTube, TikTok, Instagram.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Cloud-hosted MCP server for durable AI memory
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/EezyMAcc/mcp-loop-build-demo'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
