Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
Scored across 6 tools
Each tool targets a distinct resource or action: full artwork records (get), vocabulary values (lookup), and searches across four clearly different domains (artworks, artists, exhibitions, audio guide). No two tools overlap in a way that would cause misselection.
All six tools follow the same `artic_` prefix plus consistent verb_noun convention (get_artworks, lookup_vocabulary, search_artists, search_artworks, search_exhibitions, search_audio_guide). The pattern is fully predictable.
Six tools is a well-scoped set for a read-only museum collection API, covering search, retrieval, and vocabulary lookup without redundancy. Each tool clearly earns its place.
The surface covers the core discovery lifecycle: search across artworks/artists/exhibitions/audio, look up filter vocabulary, and fetch full artwork records. Minor gaps exist (no dedicated full artist or exhibition detail record beyond search results, no pagination helper), but agents can work around these via search.
Fetch full Art Institute of Chicago records for the first 10 artworks by id, returning deferred_ids for the rest: description, provenance, exhibition and publication history, dimensions, inscriptions, credit line, categorization, gallery, image URLs with rights status, and related multimedia. Long histories are opt-in through sections. Ids come from artic_search_artworks, artic_search_exhibitions, or artic_search_artists.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Artwork ids as an array or comma-separated string, up to 1,000 supplied entries including blanks and duplicates. Comma strings also have a 100,000-character ceiling. Artwork page URLs are read as their id; blanks and duplicates are dropped. Fetches the first 10; deferred_ids names the remainder. | |
| sections | No | Heavy text sections to include: description (also short_description), provenance, exhibition_history, publication_history, catalogue. Defaults to description and provenance; pass an empty array for none. | |
| include_related_media | No | Load related multimedia (lectures, audio stops) for the records, up to 20 items per call. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when ids are missing or deferred, or related media was capped or could not load. |
| artworks | No | Records in request order; ids the museum does not have are left out. |
| missing_ids | No | Attempted ids with no artwork, in request order; unattempted ids are not reported as missing. |
| deferred_ids | No | Ids left out by the response budget or beyond the first 10 attempted ids, in request order; pass them to artic_get_artworks again. |
| license_text | No | License statement from the API for this data, verbatim. |
| description_attribution | No | Attribution owed for description text (CC BY 4.0); present when any is returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld), so credit goes for the added behavior: only the first 10 records are fetched with deferred_ids naming the remainder, plus the sections opt-in and media default. This batching/partial-return behavior is material and not derivable from annotations.
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?
Front-loaded with the action and batching behavior, with no filler sentences. The long enumeration of returned fields is somewhat redundant given a full output schema exists, but it remains readable and mostly earns its place.
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 output schema exists and annotations carry safety, the description covers the remaining essentials: id sourcing, the 10-record cap with deferred_ids, and section opt-in defaults. Complete enough that an agent needs nothing further to invoke it 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?
Schema description coverage is 100%, so the schema already documents ids, sections, and include_related_media thoroughly. The description's mention of sections as opt-in and related multimedia restates rather than extends the schema, so the baseline 3 holds.
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?
States a specific verb and resource ('Fetch full Art Institute of Chicago records ... by id') and immediately distinguishes itself from the search siblings by naming where ids come from (artic_search_artworks, artic_search_exhibitions, artic_search_artists). An agent can tell it apart from the search tools without opening a schema.
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 routes usage by identifying upstream tools that produce valid ids, implying the search-then-fetch workflow, and notes that heavy histories are opt-in. It stops short of explicit when-not guidance, but the context is clear enough to select the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the values of an Art Institute of Chicago collection vocabulary with how many artworks carry each, most common first, optionally narrowed by a substring. Each value passes to the artic_search_artworks filter of the same name exactly as listed (case is ignored). Counts here span the whole collection; for counts within a filtered set of artworks, request facets from artic_search_artworks.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Requested values, most common first (1-1,000); at most 100 are returned. Narrow with contains for more specific values. | |
| contains | No | Case- and accent-insensitive substring the values must contain, such as "impress" for Impressionism and Post-Impressionism, or "applique" for appliqué (technique). Omit to list the most common values. | |
| vocabulary | Yes | Vocabulary to list; its values feed the artic_search_artworks filter of the same name. | |
| public_domain_only | No | Count only public-domain artworks. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Values returned. |
| notice | No | Guidance when no value matched or the list was capped. |
| values | No | Values, most common first. |
| truncated | No | True when more values exist beyond the limit. |
| vocabulary | No | The vocabulary listed. |
| filter_param | No | The artic_search_artworks parameter that accepts these values as listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are ordered most-common-first, matching is case-insensitive, and counts are collection-wide rather than filter-scoped. No auth or rate-limit notes, which is a minor gap.
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 with no filler, each carrying distinct information (what is returned, how the values are reused, how counts differ from facets). The core purpose is front-loaded in the first 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?
An output schema exists, so return formatting need not be restated. Combined with 100% parameter coverage and a clear statement of count scope, ordering, and filter interop, nothing needed to invoke this correctly is missing.
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 100%, so the baseline is 3, but the description adds meaning the schema does not: values from this list are passed to the same-named artic_search_artworks filter verbatim and case is ignored. It also frames the substring parameter as the way to reach narrower values.
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?
States a specific verb and resource (list Art Institute collection vocabulary values) plus the exact payload returned (counts per value, most-common-first ordering). It also names the sibling artic_search_artworks and the distinct facet path, so an agent can separate it from the search/get siblings without opening any schema.
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?
Explicit routing: use this for whole-collection counts, and use artic_search_artworks facets for counts within a filtered set. It also states the optional substring narrowing, giving both when-to-use and when-to-use-something-else.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find artists, cultures, and organizations in the Art Institute of Chicago collection by name, or fetch them by id. Each result carries life dates, agent type, alternate names, how many of the museum's artworks credit them, and up to three of their works, the museum's highlighted works first. Pass an id to artic_search_artworks as artist_id to browse all of their works.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Agent ids as an array or comma-separated string, up to 1,000 supplied entries including blanks and duplicates. Comma strings also have a 100,000-character ceiling. Blanks and duplicates are dropped; fetches the first 25 and returns deferred_ids. Pass query or ids, not both; other filters and page apply to query only. | |
| page | No | Query mode: page to return (1-based); page times the applied limit may not exceed 1,000. | |
| limit | No | Query mode: requested agents per page (1-1,000); at most 25 are returned. | |
| query | No | Name to find, matched against names and alternate names; every word must match. Pass query or ids, not both. | |
| born_to | No | Query mode: latest birth year, negative for BCE. | |
| born_from | No | Query mode: earliest birth year, negative for BCE. | |
| artists_only | No | Query mode: only agents the museum records as artists. Set false to include donors, funds, and organizations. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page, or the number of ids attempted (up to 25). |
| page | No | Page returned (1-based); always 1 when ids were passed. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Agents returned on this page. |
| notice | No | Guidance when nothing matched, ids were missing, more pages exist, the reachable window is exhausted, or artwork counts could not be loaded. |
| artists | No | Matching agents: in relevance order for a name search, in request order for ids. |
| has_more | No | True when more query matches exist beyond this page, or ids mode has deferred ids. |
| next_page | No | Page to request next; absent when nothing remains or the next page would pass the first 1,000 matches. |
| truncated | No | True when more query matches exist beyond this page, or ids mode has deferred ids. |
| totalCount | No | Matches for the query and filters before paging, or agents found among attempted ids. |
| missing_ids | No | Attempted ids with no agent, in request order; present in ids mode. Deferred ids have not been checked. |
| deferred_ids | No | Unattempted ids beyond the first 25, in request order; pass them as ids to artic_search_artists again. Present in ids mode. |
| license_text | No | License statement from the API for this data, verbatim. |
| artists_only_applied | No | Whether results were limited to artists; always false when ids were passed, since every requested agent is returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results carry life dates, agent type, alternate names, credit counts, and up to three works with museum-highlighted ones ordered first, plus the id hand-off pattern.
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, zero waste. The core purpose and dual modes are front-loaded, the result-shape detail follows compactly, and the closing sentence handles cross-tool routing. Every clause earns its place.
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 present, annotations covering the safety profile, and 100% schema description coverage, the description only needs to supply purpose, result flavor, and routing — all of which it does. Nothing required to invoke it correctly is missing.
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 100%, so the schema already documents all seven parameters including the query/ids exclusivity and page/limit caps. The description adds no parameter syntax or format meaning beyond 'by name, or fetch them by id.' Baseline 3 applies when the schema carries the parameter burden.
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?
States a specific verb and resource ('Find artists, cultures, and organizations in the Art Institute of Chicago collection by name, or fetch them by id'), covering both query and id-fetch modes. This clearly separates it from siblings like artic_get_artworks and artic_search_artworks without needing to open a schema.
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 routes the agent: 'Pass an id to artic_search_artworks as artist_id to browse all of their works,' naming the sibling and the follow-up condition. It also notes query-vs-ids exclusivity, though that is repeated from the schema rather than adding new guidance about when not 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.
Search the Art Institute of Chicago collection by text and structured filters, ranked by relevance or sorted by date. Text matches all words across titles, artists, descriptions, provenance, and other catalog fields. Filters combine with AND. Results reach the first 1,000 matches; narrow with filters for more. Set limit to 0 with facets to get only counts. Use artic_lookup_vocabulary for filter values and artic_get_artworks for full records.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page to return (1-based); page times the applied limit may not exceed 1,000. | |
| sort | No | relevance ranks by query text, or by museum popularity without it; date_asc and date_desc sort by start year. | relevance |
| limit | No | Requested rows per page (0-1,000); at most 12 are returned. 0 returns only totalCount and facets. | |
| query | No | Text matched against titles, artists, descriptions, provenance, and other catalog fields; every word must match. Supports "exact phrase", -exclude, and a | b. | |
| style | No | Style title as artic_lookup_vocabulary lists it (case ignored), such as Impressionism; matches preferred or alternate styles. | |
| theme | No | Theme title as artic_lookup_vocabulary lists it (case ignored), such as Women artists. | |
| artist | No | Artist or culture name matched against every credited artist (all words must match). | |
| facets | No | Facet counts to compute over the filtered set (top 15 values each): department, artwork_type, style, subject, classification, place_of_origin, artist. An array or a comma-separated string. | |
| gallery | No | Gallery where the work is on view, such as Gallery 240 (a bare 240 is read as Gallery 240). Only on-view works carry a gallery. | |
| subject | No | Subject title as artic_lookup_vocabulary lists it (case ignored). | |
| year_to | No | Latest year; a work matches when its date span overlaps year_from to year_to. Negative for BCE. | |
| material | No | Material title as artic_lookup_vocabulary lists it (case ignored), such as ink or gold leaf. | |
| artist_id | No | Agent id from artic_search_artists or an artist facet row; matches preferred and other credits. | |
| has_image | No | Only works with an image. | |
| technique | No | Technique title as artic_lookup_vocabulary lists it (case ignored), such as black-and-white photography or plain weaving. | |
| year_from | No | Earliest year; a work matches when its date span overlaps year_from to year_to. Negative for BCE. | |
| department | No | Department title exactly as artic_lookup_vocabulary lists it (case ignored), such as Prints and Drawings. | |
| artwork_type | No | Artwork type title as artic_lookup_vocabulary lists it (case ignored), such as Painting or Print. | |
| on_view_only | No | Only works on view at the museum now. | |
| classification | No | Classification title as artic_lookup_vocabulary lists it (case ignored), such as oil on canvas or etching. | |
| place_of_origin | No | Place of origin as artic_lookup_vocabulary lists it (case ignored), such as france. | |
| public_domain_only | No | Only public-domain works, whose images are CC0. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| page | No | Page returned (1-based). |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Rows returned on this page. |
| facets | No | Counts over the filtered set for each requested facet; present only when facets were requested. |
| notice | No | Guidance when nothing matched, more pages exist, or the reachable window is exhausted. |
| artworks | No | Matching artworks on this page, in ranked or sorted order. |
| has_more | No | True when more matches exist beyond this page. |
| next_page | No | Page to request next; absent when nothing remains or the next page would pass the first 1,000 matches. |
| truncated | No | True when more matches exist beyond this page. |
| totalCount | No | Matches for the query and filters, before paging. |
| license_text | No | License statement from the API for this data, verbatim. |
| sort_applied | No | Order applied; popularity when relevance was requested without query text (the museum popularity ranking). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely new behavioral facts: results are capped at the first 1,000 matches and filters combine with AND, neither of which appears in the annotations. It omits any note on facet size or ranking tie-breaking, but covers the main constraint an agent must plan around.
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?
Five short sentences, each with a distinct job: purpose, matching semantics, filter logic, cap workaround, sibling routing. The most decision-relevant facts (scope and modes) are front-loaded with no filler.
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 22-parameter search tool with a full schema and an output schema, the description supplies exactly the missing pieces: result cap, filter combination logic, counts-only mode, and sibling routing. Return-value explanation is correctly left to the output schema.
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 100%, so every parameter is already documented, making 3 the baseline. The description adds only cross-parameter semantics (filters AND together, limit=0 with facets for counts) and no per-parameter meaning that the schema lacks, so it does not clearly exceed the baseline.
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?
States a specific verb and resource (search the Art Institute of Chicago collection) plus the two retrieval modes (text relevance vs. date sort). It also names sibling tools artic_lookup_vocabulary and artic_get_artworks and assigns them distinct roles, so the agent can separate this from neighbors without opening any schema.
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 routes the agent: use artic_lookup_vocabulary for valid filter values and artic_get_artworks for full records, and explains the limit=0 plus facets pattern for counts-only queries. It also gives a workaround for result caps (narrow with filters), which is actionable when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Art Institute of Chicago's mobile audio-guide stops by text, matching stop titles and transcripts. Returns each stop's title, MP3 URL, and transcript text. Stops carry no artwork id, so match a stop to a work by its title; for a known artwork, artic_get_artworks related_media lists the recordings linked to it. Some stops are in Spanish, and titles are sometimes internal file names. This content is for noncommercial educational and personal use only: keep the copyright notice and cite the Art Institute of Chicago.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page to return (1-based); page times the applied limit may not exceed 1,000. | |
| limit | No | Requested stops per page (1-1,000); at most two whole stops are returned. | |
| query | Yes | Text matched against stop titles and transcripts; every word must match. An artwork's title or the artist's surname works well. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| page | No | Page returned (1-based). |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Stops returned on this page. |
| stops | No | Matching stops on this page, in relevance order. |
| notice | No | Guidance when nothing matched, more pages exist, or the reachable window is exhausted. |
| has_more | No | True when more matches exist beyond this page. |
| next_page | No | Page to request next; absent when nothing remains or the next page would pass the first 1,000 matches. |
| truncated | No | True when more matches exist beyond this page. |
| totalCount | No | Matches for the query, before paging. |
| license_text | No | License statement from the API, verbatim: noncommercial educational and personal use, with notices retained and the source cited. |
| source_citation | No | Citation to keep with any use of this content. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnly/openWorld/idempotent, but the description adds essential context beyond them: it discloses that some stops are Spanish-language, titles can be internal file names, and there is a noncommercial-use copyright constraint. These are behavioral facts no annotation captures.
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?
Four tight sentences front-load the core action and then layer routing, caveats, and constraints. Every sentence carries information; none is filler.
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 output schema exists and annotations cover safety, the description fills the remaining gaps: linking behavior to artwork records, language quirks, title quirks, and usage licensing. Nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents query, page, and limit semantics in detail. The description adds no parameter-specific syntax beyond the schema, so baseline 3 is appropriate.
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?
States a specific verb (Search) and resource (audio-guide stops) with the matching fields (titles and transcripts). It also distinguishes itself from siblings by naming artic_get_artworks related_media as the alternative path.
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 explains when to use this tool versus artic_get_artworks: use this for text search across stops, and use related_media when you have a known artwork. It also warns that stops have no artwork id and explains the title-matching workaround.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Art Institute of Chicago exhibitions by text, date, artwork_id, or artist_id. Relationship filters cover recorded museum links; an absent link does not prove an artwork or artist never appeared in a show. Results carry dates, gallery, summary, web page, and listed artworks. Pass artwork ids to artic_get_artworks for full records.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page to return (1-based); page times the applied limit may not exceed 1,000. | |
| sort | No | relevance ranks by query text; start_desc and start_asc sort by opening date. Defaults to relevance with a query, else start_desc; relevance without a query sorts as start_desc. | |
| when | No | current: open today; upcoming: opens after today; past: closed before today; any: no date condition. | any |
| limit | No | Requested exhibitions per page (1-1,000); at most 25 are returned. | |
| query | No | Text matched against exhibition titles, descriptions, and other fields; every word must match. | |
| date_to | No | Latest date, YYYY-MM-DD; an exhibition matches when its run overlaps date_from to date_to. | |
| artist_id | No | Exact museum agent id, from artic_search_artists or an artwork artist_id; matches recorded exhibition relationships. Combined with every other condition using AND. | |
| date_from | No | Earliest date, YYYY-MM-DD; an exhibition matches when its run overlaps date_from to date_to. | |
| artwork_id | No | Exact museum artwork id, from artic_search_artworks or artic_get_artworks; matches recorded exhibition relationships. Combined with every other condition using AND. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| page | No | Page returned (1-based). |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Exhibitions returned on this page. |
| notice | No | Guidance when nothing matched, more pages exist, or the reachable window is exhausted. |
| has_more | No | True when more matches exist beyond this page. |
| next_page | No | Page to request next; absent when nothing remains or the next page would pass the first 1,000 matches. |
| truncated | No | True when more matches exist beyond this page. |
| totalCount | No | Matches for the query and filters, before paging. |
| exhibitions | No | Matching exhibitions on this page, in ranked or sorted order. |
| license_text | No | License statement from the API for this data, verbatim. |
| sort_applied | No | Order applied. |
| when_applied | No | The when condition applied. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: relationship filters only cover recorded museum links and an absent link is not proof of non-appearance, plus a note on what results carry. It omits pagination-past-25 details, which live in the schema.
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?
Four tight sentences with the purpose front-loaded and the artifact caveat placed before the routing hint. The 'Results carry dates, gallery, summary...' sentence somewhat duplicates the output schema but functions as a quick orientation.
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 present, return values need not be described, and the definition instead covers the interpretive pitfall of relationship filters and points to the follow-up tool for full records. It is complete enough for an agent to call and interpret results 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?
Schema description coverage is 100%, so the schema already documents all nine parameters, including the AND-combination semantics. The description adds the caveat that relationship filters reflect recorded links only, but otherwise defers to the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 opens with a specific verb (Search) and precise resource (Art Institute of Chicago exhibitions) plus the filter dimensions available. It distinguishes itself from artic_get_artworks by pointing that tool at full artwork records, so an agent can tell the two apart without opening schemas.
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?
It routes the agent: 'Pass artwork ids to artic_get_artworks for full records,' which is a clear alternative for one path. It also frames when relationship filters are meaningful. It stops short of explicit when/when-not guidance against siblings like artic_search_artworks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
artic_get_artworks4 fields changedInput schema / properties / ids / descriptionPrevious value: -"Artwork ids, 1 to 10, as an array or a comma-separated string; https://www.artic.edu/artworks/<id> page URLs are read as their id. Duplicates are dropped."New value: +"Artwork ids as an array or comma-separated string, up to 1,000 supplied entries including blanks and duplicates. Comma strings also have a 100,000-character ceiling. Artwork page URLs are read as their id; blanks and duplicates are dropped. Fetches the first 10; deferred_ids names the remainder."Input schema / properties / ids / maxItemsPrevious value: -10New value: +1000Output schema / properties / deferred_ids / descriptionPrevious value: -"Found ids left out because the response budget was reached; request them in a follow-up call."New value: +"Ids left out by the response budget or beyond the first 10 attempted ids, in request order; pass them to artic_get_artworks again."Output schema / properties / missing_ids / descriptionPrevious value: -"Requested ids with no artwork, in request order."New value: +"Attempted ids with no artwork, in request order; unattempted ids are not reported as missing."artic_lookup_vocabulary2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Values to return, most common first (1-100)."New value: +"Requested values, most common first (1-1,000); at most 100 are returned. Narrow with contains for more specific values."Input schema / properties / limit / maximumPrevious value: -100New value: +1000artic_search_artists14 fields changedInput schema / properties / ids / descriptionPrevious value: -"Agent ids to fetch (up to 25), such as an artwork's artist_id, as an array or a comma-separated string. Pass query or ids, not both; the other filters and page apply to query only."New value: +"Agent ids as an array or comma-separated string, up to 1,000 supplied entries including blanks and duplicates. Comma strings also have a 100,000-character ceiling. Blanks and duplicates are dropped; fetches the first 25 and returns deferred_ids. Pass query or ids, not both; other filters and page apply to query only."Input schema / properties / ids / maxItemsPrevious value: -25New value: +1000Input schema / properties / limit / descriptionPrevious value: -"Query mode: agents per page (1-25)."New value: +"Query mode: requested agents per page (1-1,000); at most 25 are returned."Input schema / properties / limit / maximumPrevious value: -25New value: +1000Input schema / properties / page / descriptionPrevious value: -"Query mode: page to return (1-based); page times limit may not exceed 1,000."New value: +"Query mode: page to return (1-based); page times the applied limit may not exceed 1,000."Input schema / properties / page / maximumPrevious value: -100New value: +1000Output schema / properties / artists / items / properties / ulan_idAdded value: +{
+ "description": "Getty ULAN authority identifier when recorded; sparse coverage. Distinct from the museum agent id used in other tools.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Output schema / properties / cap / descriptionPrevious value: -"The limit applied to this page, or the number of ids requested."New value: +"The limit applied to this page, or the number of ids attempted (up to 25)."Output schema / properties / deferred_idsAdded value: +{
+ "description": "Unattempted ids beyond the first 25, in request order; pass them as ids to artic_search_artists again. Present in ids mode.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+}Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `query_or_ids_required`: Neither query nor ids was given. `query_and_ids_conflict`: Both query and ids were given. `invalid_year_range`: born_from is later than born_to. `page_beyond_window`: page times limit exceeds 1,000, past the reachable search window. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_or_ids_required`: Neither query nor ids was given. `query_and_ids_conflict`: Both query and ids were given. `invalid_year_range`: born_from is later than born_to. `page_beyond_window`: page times the applied limit exceeds 1,000, past the reachable search window. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."Output schema / properties / has_more / descriptionPrevious value: -"True when more matches exist beyond this page."New value: +"True when more query matches exist beyond this page, or ids mode has deferred ids."Output schema / properties / missing_ids / descriptionPrevious value: -"Requested ids with no agent, in request order; present when ids were passed."New value: +"Attempted ids with no agent, in request order; present in ids mode. Deferred ids have not been checked."Output schema / properties / totalCount / descriptionPrevious value: -"Matches for the query and filters before paging, or agents found for ids."New value: +"Matches for the query and filters before paging, or agents found among attempted ids."Output schema / properties / truncated / descriptionPrevious value: -"True when more matches exist beyond this page."New value: +"True when more query matches exist beyond this page, or ids mode has deferred ids."artic_search_artworks4 fields changedInput schema / properties / limit / descriptionPrevious value: -"Rows per page (0-12; capped so a page of long catalog records with every facet stays within common tool-output limits); 0 returns only totalCount and facets."New value: +"Requested rows per page (0-1,000); at most 12 are returned. 0 returns only totalCount and facets."Input schema / properties / limit / maximumPrevious value: -12New value: +1000Input schema / properties / page / descriptionPrevious value: -"Page to return (1-based); page times limit may not exceed 1,000."New value: +"Page to return (1-based); page times the applied limit may not exceed 1,000."Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `page_beyond_window`: page times limit exceeds 1,000, past the reachable search window. `invalid_year_range`: year_from is later than year_to. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `page_beyond_window`: page times the applied limit exceeds 1,000, past the reachable search window. `invalid_year_range`: year_from is later than year_to. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."artic_search_audio_guide6 fields changedInput schema / properties / limit / defaultPrevious value: -5New value: +2Input schema / properties / limit / descriptionPrevious value: -"Stops per page (1-20)."New value: +"Requested stops per page (1-1,000); at most two whole stops are returned."Input schema / properties / limit / maximumPrevious value: -20New value: +1000Input schema / properties / page / descriptionPrevious value: -"Page to return (1-based); page times limit may not exceed 1,000."New value: +"Page to return (1-based); page times the applied limit may not exceed 1,000."Input schema / properties / page / maximumPrevious value: -200New value: +1000Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `page_beyond_window`: page times limit exceeds 1,000, past the reachable search window. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `page_beyond_window`: page times the applied limit exceeds 1,000, past the reachable search window. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."artic_search_exhibitions7 fields changedInput schema / properties / artist_idAdded value: +{
+ "description": "Exact museum agent id, from artic_search_artists or an artwork artist_id; matches recorded exhibition relationships. Combined with every other condition using AND.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Input schema / properties / artwork_idAdded value: +{
+ "description": "Exact museum artwork id, from artic_search_artworks or artic_get_artworks; matches recorded exhibition relationships. Combined with every other condition using AND.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Input schema / properties / limit / descriptionPrevious value: -"Exhibitions per page (1-25)."New value: +"Requested exhibitions per page (1-1,000); at most 25 are returned."Input schema / properties / limit / maximumPrevious value: -25New value: +1000Input schema / properties / page / descriptionPrevious value: -"Page to return (1-based, 1-40); page times limit may not exceed 1,000."New value: +"Page to return (1-based); page times the applied limit may not exceed 1,000."Input schema / properties / page / maximumPrevious value: -40New value: +1000Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_from is later than date_to. `page_beyond_window`: The API refused the page as past the first 1,000 matches (the page and limit bounds keep calls inside it). `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_from is later than date_to. `page_beyond_window`: page times the applied limit exceeds 1,000, past the reachable search window. `rate_limited`: The Art Institute API throttled this server and retries ran out, or the shared request queue could not start the call in time. `request_blocked`: The Art Institute API's firewall blocked the request, as it does for markup or script-like text and for bursts of traffic. `upstream_rejected_query`: The Art Institute API rejected a request this server built from valid inputs. Other values are possible when a failure originates below the handler."artic_get_artworksartic_lookup_vocabularyartic_search_artistsartic_search_artworksartic_search_audio_guideartic_search_exhibitionsSearch 14.5M Smithsonian Open Access objects, get CC0 images, find cross-collection connections.
Art Institute of Chicago MCP — wraps the ARTIC public API (free, no auth)
Find artist-credited art prints and canvas, made to order by Image Kind’s studio.
Add one secure layer between your agents and this server.