Skip to main content
Glama

Most-Famous-Paintings Masterpiece Guide

Search artworks

search_artworks
Read-onlyIdempotent

Keyword search of ONE model, the artworks: words of the title, the artist name and the description. Use it when you are looking for a work (a painting, a drawing, a sculpture). When the words may name an artist, a museum or an article instead, use search_fts, which searches the four models in one call; when you have a sentence or a paragraph and no name, use search_objects_semantically. Optional artist: only the works of that artist, the query words matched against ALL of them (artist_artworks_count says how many) - without query, his most popular works. To find out whether a half-remembered work is in the catalog, use find_artwork_in_catalog (one call) rather than many searches with title variants. Returns only good-confidence matches with pk, artist_name, title, url, image_url (absolute URL of the large artwork image, null when the artwork has no image) and relevance score.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_artworks"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of results (1-10, default 10).
queryNoWords from the artwork title, artist name and/or description (optional when artist is given).
artistNoOptional artist name: search only his works.
languageNoSite language code (2 letters, e.g. "en", "fr"). Default "en".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / artist
      Added value: +{
      +  "description": "Optional artist name: search only his works.",
      +  "type": "string"
      +}
    • changedInput schema / properties / query / description
      Previous value: -"Words from the artwork title, artist name and/or description."New value: +"Words from the artwork title, artist name and/or description (optional when artist is given)."
    • removedInput schema / required
      Removed value: -[
      -  "query"
      -]
  2. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered; the description still adds real behavioral context, notably that only good-confidence matches are returned, the null-image convention, and that an artist-only query returns his most popular works. It does not discuss result paging or ordering other than popularity, 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and sibling routing are front-loaded, and nearly every clause carries information. The dense hyphen-and-parenthesis style makes it harder to parse than it needs to be, and the return-field list could be tighter, but there is no filler.

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 four-parameter read-only search with no output schema, the description supplies the routing rules, the optional-artist semantics, the confidence filter, and an explicit enumeration of returned fields including the null-image case. An agent has everything needed to call it correctly and interpret the response.

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 description genuinely extends the schema: it explains that with artist set the query words are matched against ALL of that artist's works, and that omitting query yields his most popular works. It also references artist_artworks_count as a way to gauge result volume, which the schema never mentions.

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 ("Keyword search of ONE model, the artworks") and immediately enumerates the searched fields (title, artist name, description) and the entity type (painting, drawing, sculpture). It explicitly contrasts itself with search_fts and search_objects_semantically, so an agent can discriminate it from siblings without opening another schema.

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?

Provides explicit when-to-use and when-not-to-use routing: name-like words go to search_fts (four models in one call), a sentence with no name goes to search_objects_semantically, and a half-remembered work should use find_artwork_in_catalog in one call instead of many variant searches. It also covers the degenerate case of artist without query, naming the fallback behavior.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.