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

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those: DB-backed performance characteristics, the exact direct-record response style, stateless pagination that is not portable across server upgrades, and the verbosity/suppression behavior of includeExtentText. No contradiction 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.

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

The description is dense but justifiably so — it covers source data, return fields, pagination, a performance trait, a verbose-flag caveat, and usage boundaries. It is front-loaded with the core purpose. Slightly long, but every sentence earns its place; only a small reorganization into bullets could make it more scannable.

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 tool's complexity and the presence of a rich output schema, the description covers everything an agent needs to invoke it correctly: how to obtain setSpec, what records look like, when to call get_artwork_details, pagination semantics, and the exclusion for set discovery. Nothing critical 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 baseline is 3. The description adds extra semantic value by explaining where setSpec comes from, that resumptionToken makes setSpec ignored, and that includeExtentText defaults to false because the field is large and not rendered in the text channel. This goes beyond the raw schema.

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 and resource: 'Enumerate the member artworks of one curated set by setSpec.' It also explicitly distinguishes itself from list_curated_sets ('Not for set discovery') and positions itself relative to get_artwork_details, so an agent can tell exactly what this tool does versus siblings.

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 gives explicit prerequisites ('Get setSpec values from list_curated_sets'), tells the agent when this tool is not appropriate ('Not for set discovery — use list_curated_sets first'), and names the follow-up alternative for more detail ('follow up with get_artwork_details'). This is strong, decision-ready guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructiveness, so the description does not need to repeat those. It adds useful behavioral context beyond the annotations: 'Local and resolver-free' clarifies that no external resolver is needed, and the reverse-bibliography framing explains what kind of lookup this performs.

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 short sentences carry all essential information: purpose, input provenance with example, and an exclusion. It is front-loaded with the core meaning and contains 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?

Given the annotations, schema descriptions, output schema, and the two-parameter simplicity, the description covers everything an agent needs to invoke the tool correctly. It explains the input source, the intended usage, and what the tool is not for, making it complete for this context.

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. The description adds value by providing a concrete example URI and explicitly tying the publication parameter to the output of get_artwork_bibliography, which helps the agent construct a valid input even beyond the schema's description.

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 clearly identifies a specific verb and resource: finding artworks that cite a given publication URI or id. The phrase 'Reverse bibliography' immediately distinguishes it from related tools, and the explicit 'Not for topic search of the library catalogue' prevents confusion with search_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?

The description gives concrete guidance on what input to use and where to obtain it: 'Use the publicationUri from get_artwork_bibliography'. It also states an explicit when-not condition, 'Not for topic search of the library catalogue,' which helps an agent choose between this and sibling tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the description's job is to add context. It does: default returns first 5 plus total count, full=true can return 100+ entries, ISBN/publication details appear 'where known', and entries may carry a [pub NNN] handle. No contradiction 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.

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

Four sentences with no filler: purpose, content details, workflow, exclusions, and pagination behavior are all packed efficiently. The most decision-relevant information is front-loaded, and the context-window warning 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 and annotations covering the safety profile, the description is complete for correct invocation. It explains what the entries contain, how pagination works, how to follow up on linked publications, and when not to use the tool. No critical gap remains.

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 baseline is 3. The description adds value by explaining the trade-off of full=true in terms of context window and 100+ entries, and by reinforcing that objectNumber is the key selector. This is modest but useful enrichment beyond the schema.

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 action and resource: scholarly references/citations for ONE artwork by objectNumber. It also distinguishes itself from siblings by stating 'Not for general metadata — use get_artwork_details' and explaining the [pub NNN] handle flow to find_artworks_citing_publication.

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 clearly states when the tool is appropriate: after a search_artwork or get_artwork_details result. It also gives explicit exclusions: not for general metadata and not for library-catalogue search, naming the alternative get_artwork_details. The default-versus-full behavior is also explained.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint; the description adds substantial behavioral detail beyond those: the two-level authority ID structure, the relatedObjects hand-off via objectNumber/iiifId/objectUri, and the caveat that some entries, like iconclass terms, carry no authority IDs. There is no contradiction 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.

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

The description is long but information-dense and well organized: scope first, then detailed return content, then routing guidance and exclusions. Each sentence earns its place, and the key usage constraint is front-loaded.

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, annotations, and parameter descriptions, this tool definition is complete. It covers input requirements, return contents, related-object navigation, authority IDs, and exclusions. There are no significant gaps that would prevent an agent from selecting and invoking 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?

Although the schema covers each parameter, the description adds a crucial constraint absent from the schema: exactly one of objectNumber or uri must be supplied, with objectNumber preferred. It also explains verboseExtent's default behavior and how structured dimensions relate to it, resolving ambiguity the schema leaves open.

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 operation: 'Full metadata for ONE artwork by objectNumber,' and clarifies the two accepted identifier forms. It is immediately distinguishable from sibling tools like search_artwork and get_artwork_image.

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 explicitly states when to use the tool: after search_artwork, semantic_search, find_similar, or when a user supplies an objectNumber. It also gives clear negatives: not for filter-based discovery, not for similarity discovery, and not for aggregate counts, naming the appropriate alternatives.

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

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

The description discloses important behavior beyond the annotations: it returns metadata and a viewer link rather than image bytes, not all artworks have images, and agents should not manually construct or fetch IIIF URLs. It also implies a stateful viewer interaction, consistent with openWorldHint. No contradiction with the 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?

The description is compact yet information-dense: each sentence serves a purpose, starting with the core action and then layering usage constraints, alternatives, caveats, and return-type expectations. It avoids redundancy with the schema.

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 tool that opens an interactive viewer, the description covers what it returns, when it should be used, who the alternative is for, edge cases (missing images), and an explicit warning about URL construction. The presence of an output schema further reduces the need to explain return values.

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?

There is only one parameter, objectNumber, and the input schema already describes it with an example, giving 100% schema coverage. The description adds context around image availability but does not need to add parameter-specific semantics. 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?

The description clearly states what the tool does ('Opens an interactive deep-zoom viewer for the user') and distinguishes it from inspect_artwork_image, which returns image bytes. It also scopes the resource to artwork viewing, making the purpose unmistakable.

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 gives explicit use conditions ('Use only when they ask to see, show, or view an artwork'), explicit exclusions ('not for list, summary, count, or text-only requests'), and names a concrete alternative ('use inspect_artwork_image to get image bytes'). This is strong routing guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description goes further by disclosing the concrete contents: technical examinations, treatment events, a count of signature/inscription marks (not transcriptions), and a provenance excerpt. This fully sets agent expectations.

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 dense sentences, each earning its place: scope, sequencing, return contents, and explicit exclusions. No filler or repetition of annotation information.

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 single-parameter, read-only tool with an output schema, the description fully covers when to use it, how to use it, what it returns, and what it explicitly avoids. Nothing critical 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% and the only parameter, objectNumber, already has a clear description with examples. The description's 'by objectNumber' adds little beyond the schema, so the 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+resource ('Technical examinations and restoration history for ONE artwork') and enumerates exactly what it returns. Explicitly distinguishes itself from get_artwork_details and other tools by declaring what it is not for.

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?

Provides explicit sequencing guidance: use after get_artwork_details or a search result, keyed by objectNumber. Also gives clear exclusion criteria with named alternatives for general metadata, transcriptions, and aggregate counts.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: pagination anchored to a harvest checkpoint, deleted records flagged with deleted:true and [DELETED], identifiersOnly records carrying only a LOD URI, and identifiersOnly being preserved across continuation pages. This materially helps an agent predict results and plan follow-up actions.

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?

The description is dense but front-loaded with the tool's core purpose. Every sentence adds distinct value: delta scope, pagination, identifiersOnly mode, follow-up behavior, and deleted-record handling. No filler or redundancy.

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 six-parameter paginated feed tool, the description covers the critical behavioral context: harvesting workflow, continuation tokens, mode differences, follow-up flow, and deleted-record semantics. An output schema exists, so return-value details do not need to be repeated here.

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 all parameters well. The description adds extra meaning by explaining trade-offs between identifiersOnly and full mode, the follow-up capabilities of objectNumber, and the special shape of deleted records. This goes beyond the parameter descriptions and improves correct parameter choice.

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 clearly identifies the tool as an OAI-PMH delta feed for records changed within a date range, with a specific verb and resource. It also distinguishes its role from sibling tools by framing it around harvest checkpoints and follow-up detail/image calls.

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 gives explicit within-tool guidance: use identifiersOnly=true for lightweight listing, and re-run without it to act on a change. It also explains when full-mode records enable follow-up calls. It does not explicitly state when not to use this tool versus sibling alternatives, but the intended workflow is clear.

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

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

Annotations already mark the operation read-only, idempotent, and non-destructive, and the description adds concrete behavior: the server never upscales beyond the region's own pixels, tight regions reveal more real detail, viewer auto-navigation occurs, and the response includes crop dimensions and viewUUID. This is substantial behavioral context beyond what annotations provide.

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 purpose and exclusions, then organized into region behavior and viewer behavior. Despite its length, each sentence adds operational value and there is 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 parameter-rich image inspection tool, the description covers target audience, region syntax, resolution behavior, viewer coordination, and relevant response fields. Since an output schema exists, return-value details do not need to be repeated here.

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?

The input schema already has 100% parameter coverage, but the description adds practical meaning: region syntax variants are explained with usage guidance, crop_pixels should be paired with nativeWidth/nativeHeight from a prior response, tight regions give more real detail, and navigateViewer behavior is clarified. This goes well beyond the schema's descriptions.

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 and resource: 'Returns image bytes (base64) for the LLM's own visual analysis.' It immediately distinguishes the tool from get_artwork_image and search_artwork, so an agent knows exactly what it is for and what it is not for.

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 alternatives and conditions: 'not for the user to view (use get_artwork_image)', 'Not for listing or summarising artworks — use search_artwork', and notes that navigateViewer removes the need for a separate navigate_viewer call. This is clear when-to-use versus when-not-to-use guidance.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that by explaining what each result carries (memberCount, dominantTypes, dominantCenturies, category) and describing the category heuristic with concrete values. It does not contradict the 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?

The description is well-structured and front-loaded: purpose, scope, result contents, usage recommendation, sibling pairing, then exclusions. Every sentence adds distinct value and none is redundant with the schema or annotations.

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?

The tool has 5 optional parameters, an output schema, and read-only annotations, and the description still covers the key contextual gaps: result semantics, category meanings, umbrella avoidance, and alternatives. An agent has enough information to decide when to call this tool and how to shape its parameters.

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 base is strong. The description adds cross-parameter guidance not present in any single schema field: the specific minMembers/maxMembers combination of 100/200000 and the intent behind it (avoiding umbrella sets). This elevates parameter semantics from a baseline 3.

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 and resource: 'Browse thematic sets curated by Rijksmuseum staff.' It also distinguishes itself from siblings by explicitly stating it is 'Not for keyword search across artworks — use search_artwork' and 'Not for aggregate counts — use collection_stats,' and it references browse_set for enumeration.

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 gives concrete when-to-use guidance: 'Use minMembers: 100, maxMembers: 200000 to avoid umbrella sets when the user wants a substantive subset.' It also names explicit alternatives for other intents, saying to pair with browse_set to enumerate members and to use search_artwork or collection_stats for other queries.

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

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

Annotations provide no safety signals (readOnlyHint=false, destructiveHint=false), so the description carries the full behavioral burden. It thoroughly discloses the coordinate space defaults, out-of-bounds rejection behavior, the 10-command batch limit, the 30-minute viewer session timeout, and the queued vs. delivered deliveryState semantics. No annotation contradiction exists.

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?

The description is long, but the tool has genuinely complex coordinate semantics. It is front-loaded with the core purpose, then clear exclusions, followed by well-organized sections for formats, errors, limits, session behavior, and delivery states. Each sentence contributes necessary operational detail; this is appropriately sized for the complexity.

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 tool with two required parameters, intricate coordinate space rules, and delivery-state nuances, the description is complete. It covers prerequisites, alternatives, coordinate formats, error handling, batching limits, session expiry, and response-field interpretation, leaving no critical gap for an agent to call 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?

Although the input schema covers all parameters, the description adds substantial meaning beyond it: every region format is explained ('pct', 'crop_pixels', legacy 'x,y,w,h', 'full', 'square'), the relativeTo coordinate projection is clarified, and relativeToSize is tied to inspect_artwork_image's cropPixelWidth/cropPixelHeight. This goes well beyond the schema descriptions.

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 states a specific verb and resource ('Zooms/pans an already-open viewer to a region') and immediately differentiates it from sibling tools: it is not for opening the viewer (use get_artwork_image) and not for visual analysis (use inspect_artwork_image). An agent can distinguish it from its siblings without inspecting 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?

The description gives explicit when-to-use and when-not-to-use guidance, including the important note that 'in most cases you do NOT need this tool' because inspect_artwork_image already auto-zooms. It also names alternatives and the prerequisite (viewer must be open from a prior get_artwork_image call).

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

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

Annotations are all false, so description must disclose behavior. It does not clarify if polling is blocking or non-blocking, what happens on no commands, or any side effects. Polling typically implies non-destructive reads, but annotations contradict by setting readOnlyHint to false, creating ambiguity.

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?

The description is concise (one sentence) and front-loaded with 'Internal:', which is useful. However, it sacrifices necessary detail for brevity, making it insufficient for an agent to use correctly.

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 tool's simplicity (one param) and existence of an output schema, the description still falls short. It fails to explain the return format, polling behavior, or how it fits with sibling tools like 'navigate_viewer' or 'remount_viewer'. Essential context 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 0%, so the description must explain the required parameter 'viewUUID'. It does not, leaving the agent to guess its purpose (likely a viewer identifier). No constraints or format details are provided.

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 clearly identifies the tool's purpose: polling for pending viewer navigation commands. The verb 'poll' and resource 'pending viewer navigation commands' are specific and distinguish it from siblings like 'navigate_viewer' which triggers navigation.

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 lacks guidance on when to use this tool versus alternatives. The prefix 'Internal:' hints at restricted usage but does not explain polling behavior, repetition, or context (e.g., after navigating). No exclusions or alternatives mentioned.

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

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

The description discloses a concrete side effect beyond the annotations: any user highlight is cleared on remount, and it explains why. It also states that the viewUUID is preserved. Given the annotations only provide false hints, this description carries the behavioral disclosure burden well.

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 short sentences with no filler. The core action is front-loaded, followed by usage context and an important behavioral side effect. Every sentence 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?

For a simple two-parameter tool with an output schema and explicit side-effect disclosure, the description is largely complete. The only minor gap is that it does not explicitly contrast itself with navigate_viewer, though the 'Internal' label and iframe call-site reduce ambiguity.

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 baseline is 3. The description does not add additional meaning beyond the schema's own parameter descriptions for viewUUID and objectNumber.

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 uses a specific verb ('switch') and resource ('viewer') and states the key invariant of preserving the viewUUID. The 'Internal' label and iframe call-site help separate it from more general tools, though it does not explicitly name or contrast with the sibling navigate_viewer.

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 clearly states when it is used: by the artwork-viewer iframe during in-viewer related navigation. The 'Internal' prefix signals this is not a general-purpose API. However, it does not explicitly say when not to use it or name alternatives like navigate_viewer.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive; the description adds valuable behavioral detail: BM25 vs importance ranking, AND-combined array filters, exact totalResults counting, and warning behavior for shared object-number prefixes. No contradiction with annotations exists.

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?

The description is long but dense, and it is front-loaded with the core scope and exclusions. The main structural waste is the repeated 'use semantic_search' guidance appearing three times; otherwise each paragraph contributes useful routing, ranking, or follow-up information.

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 19-parameter filter tool, the description covers exclusions, minimum requirements, ranking, array semantics, result summaries, warning behavior, and follow-up calls to get_artwork_details or get_artwork_image. The output schema and rich per-parameter descriptions handle return structure and formatting details, so nothing critical is left to inference.

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 cross-parameter semantics: arrays are AND-combined, at least one filter is required, no unrestricted full-text search exists, and specific fields are recommended for different query intents. Minor deduction because it references parameters like 'subject' and 'curatorialNarrative' that are not visible as input properties in the provided schema.

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 opening phrase 'Structured filter search — artworks matching ALL given filters' names a specific verb and resource and clarifies the conjunctive behavior. It also explicitly distinguishes itself from semantic_search, find_similar, and search_persons, so an agent can route correctly 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?

The description gives explicit routing rules: free-text concepts → semantic_search, artwork similarity → find_similar, demographic person queries → search_persons first, provenance → search_provenance, aggregates → collection_stats. It also states the 'at least one filter required' constraint and provides field-selection guidance for subject, description, and curatorialNarrative.

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