Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
Scored across 6 tools
Each tool has a distinct purpose: full artwork records, vocabulary lookup, artist search, artwork search, audio-guide search, and exhibition search. The descriptions clarify boundaries, such as vocabulary lookup feeding artwork filters and get_artworks retrieving records by id. There is virtually no overlap that would cause misselection.
All tools use the same artic_ prefix followed by a verb_noun pattern in snake_case: artic_get_artworks, artic_lookup_vocabulary, artic_search_artists, artic_search_artworks, artic_search_audio_guide, and artic_search_exhibitions. The convention is highly predictable.
Six tools is well-scoped for a read-only art museum API focused on searching and retrieving collection data. Each tool has a clear role and no tool feels redundant or unnecessary.
The surface covers core read-only workflows: searching and retrieving artworks, artists, exhibitions, audio-guide stops, and vocabulary values. Minor gaps exist, such as no explicit exhibition lookup by id and no direct audio-guide stop retrieval by id, though search tools can work around these limitations.
Fetch full Art Institute of Chicago records for up to 10 artworks by id: 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, 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. | |
| 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 | Requested ids with no artwork, in request order. |
| deferred_ids | No | Found ids left out because the response budget was reached; request them in a follow-up call. |
| 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 declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely useful behavior: the 10-artwork cap, that heavy history sections are opt-in, and that image URLs carry rights status. It does not discuss error behavior when an id is unknown or partial-failure handling.
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, front-loaded with the verb and scope, and the field enumeration is dense but useful for selection. The long mid-sentence field list is slightly heavy, but no sentence is wasted.
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, the description need not explain return values, and it covers scope, source, limits, and the opt-in mechanism. The main residual gap is behavioral detail on missing/invalid ids, which is minor for a read-only fetch.
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 defaults, and include_related_media fully. The description restates the sections opt-in and the id provenance but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
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 (fetch) and resource (full Art Institute of Chicago artwork records), enumerates the returned fields, and explicitly differentiates itself from the search siblings by noting ids originate from artic_search_artworks/exhibitions/artists. An agent can distinguish it from the search tools 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?
Clearly signals the prerequisite context by stating where ids come from (the three search tools), which tells the agent this is the follow-up expand step after a search. It does not, however, state when NOT to use it or contrast against artic_lookup_vocabulary.
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 | Values to return, most common first (1-100). | |
| 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, openWorld, and idempotent, so safety is covered. The description adds genuinely non-obvious behavior on top: results are ordered most-common-first, matching is case-insensitive, and counts are whole-collection rather than scoped. It does not discuss pagination or result size limits, which keeps it short of a 5.
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 densely packed sentences with zero filler. The core purpose and sort order are front-loaded, followed by the filter hand-off and the count-scope caveat, each earning 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?
An output schema exists, so return-value explanation is unnecessary. The description covers the remaining agent-relevant concerns: ordering, case handling, count scope, and the relationship to the sibling search tool. Nothing needed 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: values pass through to the artic_search_artworks filter exactly as listed with case ignored, and counts are whole-collection. The substring/case-insensitive semantics are already in the schema, so this is additive rather than essential.
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 (list) and resource (Art Institute of Chicago collection vocabulary), plus scope details: sorted most-common-first, optionally substring-narrowed. It names the sibling artic_search_artworks and explains the relationship, so an agent can distinguish it from the search tools 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: counts here span the whole collection, whereas per-filtered-set counts require facets from artic_search_artworks. It also states the values feed the artic_search_artworks filter of the same name, which is exactly the hand-off condition an agent needs.
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 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. | |
| page | No | Query mode: page to return (1-based); page times limit may not exceed 1,000. | |
| limit | No | Query mode: agents per page (1-25). | |
| 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 requested. |
| 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 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, or agents found for ids. |
| missing_ids | No | Requested ids with no agent, in request order; present when ids were passed. |
| 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 behavior not in annotations: what each result contains (life dates, agent type, alternate names, artwork credit counts, up to three works with museum-highlighted works ordered first) and the cross-tool id handoff. It stops short of noting pagination/limits behavior, which lives only 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?
Three sentences, front-loaded with purpose and mode distinction, then result shape, then the follow-up tool. Dense and mostly waste-free, though the result-shape sentence is long enough that it slightly competes with the guidance content.
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 values need not be fully specified, yet the description still frames what comes back and how to chain into artic_search_artworks. Combined with 100% schema coverage and clear annotations, nothing an agent needs 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 description coverage is 100%, so baseline is 3; the description only restates that query matches names and that ids fetch agents, both already documented in the schema. It adds no syntax or constraint detail beyond structured fields.
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 (find/fetch) and resource (artists, cultures, organizations in the AIC collection), and explicitly distinguishes search-by-name from fetch-by-id. An agent can differentiate it from artic_search_artworks and artic_lookup_vocabulary 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?
Explicitly names the downstream tool and the parameter mapping ('Pass an id to artic_search_artworks as artist_id to browse all of their works'), giving a concrete when-to-use-it-next rule. It also reflects the query-vs-ids exclusivity that routes the agent to the right mode.
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 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 | 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. | |
| 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, openWorld, and idempotent, so the safety profile is covered. The description still adds real behavioral facts not in the annotations: the 1,000-result cap, AND-combination of filters, and the limit=0 + facets counting behavior. Only return-shape details are left to the output 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 tightly packed sentences, front-loaded with the core purpose before the routing and pagination caveats. No filler and every sentence conveys a distinct, usable fact.
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 an output schema and rich annotations, the description supplies the routing, cap, AND-combination, and facet-count behavior an agent needs. Return values are 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 the baseline is 3 without further value. The description earns above baseline by disclosing cross-parameter semantics the schema states only per-field: that filters combine with AND, that text matches across all catalog fields, and that page×limit must stay under 1,000.
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 first sentence states a specific verb (Search) and resource (Art Institute of Chicago collection) plus the scope (text and structured filters, ranked or sorted). It is unmistakably distinct from siblings like artic_search_artists or artic_search_exhibitions.
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 filter values and artic_get_artworks for full records. It also gives an actionable fallback when the 1,000-match ceiling is hit (narrow with filters) and a special-case pattern (limit 0 with facets for counts only).
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 limit may not exceed 1,000. | |
| limit | No | Stops per page (1-20). | |
| 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 only declare readOnly/idempotent/openWorld; the description adds substantial behavioral context: what is returned (title, MP3 URL, transcript), the data quirk that stops have no artwork id, that some stops are Spanish, that titles may be internal file names, and the noncommercial-use licensing constraint with citation requirement.
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-loads the core action and match semantics before routing and caveats. Dense but nearly every sentence carries load; the licensing sentence is longer than strictly needed for tool selection but is legitimate usage context.
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 values need not be explained, yet the description still summarizes them. Combined with the routing guidance, data caveats, and licensing terms, nothing an agent needs to select or call this tool 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 all three parameters (query, page, limit) are already documented in the schema, and the description's note that matching is against titles/transcripts duplicates the schema. Baseline 3 applies since the description adds little parameter-level meaning beyond the structured fields.
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's mobile audio-guide stops by text') including the match fields (titles and transcripts). It explicitly distinguishes itself from the sibling artic_get_artworks by explaining that stops carry no artwork id and that related_media is the path for a known artwork.
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?
Gives explicit when-to-use routing: use this for text search of stops, but for a known artwork use artic_get_artworks related_media. It also explains the matching strategy ('match a stop to a work by its title') and warns that titles are sometimes internal file names, which affects how to use results.
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 and date: what is on now, what is coming, or past shows on a topic. Results carry dates, gallery, summary, web page, and the artworks shown when the museum lists them. Pass artwork ids to artic_get_artworks for full records.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page to return (1-based, 1-40); page times 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 | Exhibitions per page (1-25). | |
| 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. | |
| date_from | No | Earliest date, YYYY-MM-DD; an exhibition matches when its run overlaps date_from to date_to. |
| 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, open-world reads. The description adds genuine behavioral context beyond them: results are summarized (dates, gallery, summary, web page) and artwork entries are only included 'when the museum lists them,' implying partial data that requires a follow-up artic_get_artworks call. No auth or rate-limit detail is given.
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 tight sentences: capability and scope first, return contents second, follow-up routing last. No filler or repetition.
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, the description need not enumerate return fields, and parameter semantics are fully handled by the schema. It covers scope, the artwork-id handoff to artic_get_artworks, and the partial-data caveat — everything an agent needs to select and call it.
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% and every parameter (page, sort, when, limit, query, date_from, date_to) is documented there in more detail than here. The description only gestures at 'text and date' and the now/upcoming/past framing, adding little beyond the schema. Baseline 3 applies.
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 Art Institute of Chicago exhibitions by text and date') with the two dimensions of searching named. The resource word 'exhibitions' cleanly separates it from siblings artic_search_artworks, artic_search_artists, and artic_search_audio_guide.
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?
Conveys the use contexts directly ('what is on now, what is coming, or past shows on a topic'), which maps to the `when` parameter, and explicitly routes to artic_get_artworks for full records. It never states when to prefer a sibling search tool over this one, so it stops short of explicit exclusions.
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_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)
Rijksmuseum — the Dutch national museum's collection, via its open Data
Add one secure layer between your agents and this server.