Skip to main content
Glama
chrischall

artsonia-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Download a student's artwork images

artsonia_download_artwork

Download full-resolution Artsonia student artwork images to a local folder, filter by class, grade, or recent count, and skip existing files for safe repeat runs.

Instructions

Download full-resolution images of a student's artwork to a local folder, named from the artwork title/project/grade and time-stamped to the image's source date. Optionally filter by class/project (substring), grade, and/or keep only the most-recent N (the portfolio is reliably newest-first). Re-runs are idempotent (skip_existing). Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview (the resolved filenames with estimated bytes; nothing is written) and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). write_metadata:true also saves each artwork's comments + teacher feedback as a .json sidecar next to its image. embed_metadata:true embeds title/project/grade/date into each JPEG's EXIF/IPTC. path_template (e.g. "{grade}/{project}" or "{school_year}") organizes downloads into subfolders for multi-year archives. Note: descriptive filenames need each artwork's detail page (slower) — use filename_template "{artwork_id}" for the fast id-only path.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
destYesLocal destination folder (a leading ~ is expanded). Created if missing.
gradeNoOnly artworks created in this grade, e.g. "6" or "Grade 6".
limitNoKeep only the N most recent matching artworks (portfolio is newest-first).
projectNoOnly artworks whose school-project/class name contains this (case-insensitive).
artist_idYesStudent artist_id (from artsonia_list_students).
resolutionNoImage resolution. "full" is the original (~0.7 MB each).full
write_indexNoAfter downloading, write an index.json manifest into the destination folder listing the downloaded items (artwork_id, title, file, grade, project, date). Off by default.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
path_templateNoOptional subfolder pattern under dest, composed with filename_template — e.g. "{grade}/{project}" or "{school_year}" for multi-year archives. Same tokens as filename_template; segments are slugified like filenames and empty tokens collapse (no empty folders). Paths are deterministic, so skip_existing re-runs stay idempotent. {school_year} (July–June, e.g. "2021-2022") derives from the image's Last-Modified.
skip_existingNoSkip artworks whose target file already exists (idempotent re-runs). Set false to overwrite.
embed_metadataNoEmbed each image's title/project/grade and source date (its Last-Modified, same as date_source) into the JPEG's EXIF (ImageDescription, DateTimeOriginal) and IPTC (title, keywords, date) so the metadata survives renames/moves and is searchable in Spotlight/Apple Photos. Needs each artwork's detail page (slower); applies to freshly downloaded files only (skipped files are left untouched). Off by default.
write_metadataNoAfter downloading, write a per-artwork <image-name>.json sidecar next to each image with the artwork's comments and teacher feedback (plus title/project/grade). Fetches each artwork's detail page + the student's feedback page. Off by default.
include_privateNoInclude artworks marked private in the portfolio. Set false to exclude them (excluded count is reported as private_excluded_count).
filename_templateNoFilename pattern. Tokens: {title} {project} {grade} {date} {school_year} {artwork_id}. The artwork_id is auto-appended for uniqueness if absent. Use "{artwork_id}" for the fast id-only path (no detail fetch).{grade} - {project} - {title}
set_mtime_from_sourceNoSet each file's modified time from the image's Last-Modified header (its Artsonia upload date) instead of the download moment.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.2.1

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses the two-phase confirmation/confirmToken fallback, idempotent skip_existing re-runs, sidecar and EXIF/IPTC side effects, path determinism, and the performance cost of detail-page fetches. Annotations only say readOnly=false/destructive=false/openWorld=true, so this added context is exactly the value this dimension rewards.

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?

Front-loads the core action and filter story, then layers options; nearly every clause carries new information. It is dense and slightly run-on across the confirmation and metadata sentences, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter mutation tool with no output schema, the description covers confirmation, idempotency, filtering, metadata side effects, and performance trade-offs. Its only notable gap is that it never describes the returned summary/counts on a successful run, aside from the preview-phase filenames and bytes.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the prose adds cross-parameter meaning the schema does not: the filename_template slow/fast trade-off, how path_template composes with filename_template and collapses empty tokens, and the interplay of write_metadata/embed_metadata with skipped files.

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?

States a specific verb and resource ('Download full-resolution images of a student's artwork to a local folder') with the naming/scope behavior spelled out, which cleanly separates it from read-only siblings like artsonia_get_portfolio and artsonia_get_artwork.

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?

Gives clear when-to-use context: filter options, the confirmation-first rule, and an explicit alternative path ('use filename_template "{artwork_id}" for the fast id-only path'). It stops short of naming sibling tools for discovery, but the operational guidance is strong.

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

Deploy Server

Other Tools