Skip to main content
Glama

smithsonian-mcp-server

by io.github.cyanheads

Browse Smithsonian by Category

smithsonian_browse_category
Read-onlyIdempotent

Browse Smithsonian objects within one exact category — a single museum (mode "museum"), culture, indexed date term (mode "period"), object type (mode "medium"), or subject term (mode "topic"). The value must be an exact indexed category term, not free text: resolve museum, culture, period, and topic vocabulary with smithsonian_list_terms first (object_type is not enumerable there — harvest it from smithsonian_search_objects results, and treat each casing as its own category, since a harvested object_type covers only the casing it was written in). Returns the category total count, a page of matching objects, and a museum breakdown of that page; page the full category with start and rows. For open-ended or topic discovery, start with smithsonian_search_objects instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeYesBrowse dimension: "museum" (by unit code), "culture" (by culture term), "period" (by indexed date term like "1940s" or "500-1500"), "medium" (by object type like "Paintings"), "topic" (by subject term like "Quilts").
rowsNoNumber of sample objects to return (default 10, max 50).
startNoPagination offset — 0-indexed. Page contiguously with start = page × rows.
valueYesCategory value appropriate to the mode. museum: a unit code like "NASM", "SAAM", or "NMNHBIRDS", matched literally and case-sensitively — not a museum name. culture: term, often plural or qualified ("Aztecs", "Plains Indian"). period: an indexed date term — commonly a decade ("1940s", "1860s"), but year ranges ("500-1500"), century terms ("21st century"), and BCE forms ("-2500", "BCE 1000s") are indexed too. medium: object type, usually plural ("Paintings", "Aircraft"). topic: subject term ("Quilts", "Aviation"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, period (date), and topic, call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results. Every mode matches its value exactly and case-sensitively, and for medium that split is load-bearing: casing variants are indexed as SEPARATE categories, each reporting its own total_count ("button" and "Button" are different categories, and neither casing is reliably the larger), so browse the variants of a harvested value rather than assuming one covers the concept.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe rows cap that was applied.
modeNoBrowse dimension used for this request (one of "museum", "culture", "period", "medium", "topic").
errorNoPresent when the call failed. Absent on success.
shownNoNumber of sample objects returned.
valueNoCategory value queried, as provided in the request.
noticeNoGuidance naming the input that retrieves the objects this page omitted.
truncatedNoTrue when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.
total_countNoTotal number of Smithsonian objects matching this category.
sample_objectsNoThe requested page of objects matching the category, in upstream order. Empty when start is past the end of the category.
museum_breakdownNoWhen mode is not "museum": top contributing museums from the sample, helping plan museum-focused follow-up searches.
truncationCeilingNoTotal matching objects (upper bound for omitted items).

TDQS

A5/5.0
Behavior5/5

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses exact case-sensitive matching, emphasizes that medium casing variants are separate categories with independent totals, and states the return shape (total count, page, museum breakdown) plus pagination semantics. No contradictions with annotations.

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 dense but every sentence contributes: it opens with the core purpose, then flow constraints, then return and pagination, then the alternative tool. No filler; the structure flows logically from what→how→when-not.

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

Completeness5/5

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

For a complex 4-parameter tool with five modes, the description fully specifies required vocabulary resolution, exact matching behavior, the casing split, return contents, pagination, and routing to sibling tools. An output schema exists to cover return details, so nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds substantial practical meaning: it explains each mode's value format with concrete examples (unit codes, decade terms, BCE forms), the casing sensitivity trap for medium, and how to obtain valid values. This goes well beyond the schema's descriptions and is critical for correct invocation.

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 ('browse Smithsonian objects') and scope ('within one exact category'), enumerates the five modes, and explicitly contrasts with the open-ended smithsonian_search_objects. This clearly delineates its purpose from siblings and gives the agent a precise mental model.

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

Usage Guidelines5/5

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

It gives explicit when-to-use instructions: resolve museum/culture/period/topic via smithsonian_list_terms, harvest medium from smithsonian_search_objects, and 'For open-ended or topic discovery, start with smithsonian_search_objects instead.' It also warns against free-text values, making the usage constraints unambiguous.

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

All smithsonian-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

Each tool has a clearly distinct role: browsing an exact category, searching free-text, retrieving object metadata, fetching media, listing vocabulary, and finding related objects. Overlaps like browse_category vs search_objects are well-explained with explicit guidance on when to use each, eliminating ambiguity.

Naming Consistency5/5

All tools follow the same pattern: 'smithsonian_' prefix with lowercase snake_case verb_noun names (e.g., browse_category, get_media, list_terms). The naming is perfectly uniform and intuitive.

Tool Count5/5

Six tools cover the full spectrum of Smithsonian discovery and retrieval without bloat. Each tool addresses a distinct need, and the count is well-scoped for a read-only museum API.

Completeness5/5

The surface covers search, exact-category browsing, term vocabulary enumeration, object metadata retrieval, media access, and related-object discovery. There are no obvious dead ends—record IDs flow from search to other tools, and gaps like non-CC0 media are explicitly handled.

Resources