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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description adds value through latency expectations ('warm calls in tens of ms'), pagination token semantics (stateless base64, not portable across server upgrades), and the record field list. It stops short of discussing error behavior or auth, so it is strong but not exhaustive.

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 core action, then routing, return shape, and the exclusion last. Four dense sentences with little waste, though the return-field enumeration is somewhat long given an output schema exists.

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 needn't be spelled out, yet the description still summarizes fields and gives pagination behavior and follow-up routing. Complete enough for an agent to call correctly; minor gaps are only around failure modes.

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 four parameters and baseline would be 3. The description still adds meaning beyond the schema: setSpec provenance from list_curated_sets, the resumptionToken statelessness/upgrade caveat, and the note that includeExtentText is large and not rendered in the text channel.

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 (Enumerate) and resource (member artworks of one curated set) scoped by setSpec. It explicitly names the sibling tools it is not (list_curated_sets for discovery, get_artwork_details for details), so an agent can distinguish it 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?

Provides explicit routing: get setSpec from list_curated_sets, follow up with get_artwork_details for multi-row vocab, and 'Not for set discovery — use list_curated_sets first.' Both when-to-use and when-not-to-use are covered with named 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?

Annotations already declare readOnly, idempotent, and non-open-world behavior; the description reinforces this by stating the lookup is 'local and resolver-free', which tells the agent no network resolution is needed. It does not mention the default 20-item cap or total-count behavior, though that is covered in the schema's `full` parameter.

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 clauses, front-loaded with the core purpose, then input source, then exclusion. 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?

With annotations covering safety semantics and an output schema covering returns, the description only needs to explain what the tool does and what to feed it – both present. The pagination default is left to the schema, which is acceptable.

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 real value beyond the schema by giving a concrete example URI and explaining that a bare publication id is also accepted.

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 ('artworks citing a given publication URI or id') and frames it as a 'reverse bibliography', which immediately distinguishes it from the forward-direction sibling get_artwork_bibliography. An agent can pick correctly without opening either 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?

Gives explicit input provenance ('Use the publicationUri from get_artwork_bibliography') and one exclusion ('Not for topic search of the library catalogue'). The exclusion references something outside the sibling list, so it is less useful than naming a sibling tool would be, but the positive routing 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 mark this as a safe idempotent read, and the description goes well beyond them: it discloses the default truncation (first 5 plus a total count), the escape hatch (full=true), the magnitude of a full result (100+), and a context-window warning. The [pub NNN] handle convention is behavior an agent could never infer from 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?

Six tightly packed sentences, front-loaded with purpose, then output shape, then chaining, then exclusions. No filler and no repetition of the title.

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 two-parameter read tool with an output schema, everything an agent needs is present: scope, default vs full behavior, chaining handle, and both negative cases. Return-value documentation 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 the baseline is 3, but the description adds operational meaning the schema does not: what a default call actually returns (5 entries plus a count), when to escalate with full=true, and the cost of doing so. That is more than a restatement of the field docs.

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 — scholarly citations for ONE artwork, keyed by objectNumber — and immediately distinguishes it from get_artwork_details (general metadata) and the library catalogue. An agent can tell this apart from every sibling without opening the 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 positions the tool in a workflow ('Follows a search_artwork / get_artwork_details result') and names two exclusions with the correct alternative in each case. It also routes the agent onward via the [pub NNN] handle to find_artworks_citing_publication.

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 readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description does add useful behavioral nuance — that a single entity can carry several authority entries and every entry must be read, and that iconclass terms carry none — but it never covers auth, rate limits, or pagination, and most of its text restates return fields the output schema already defines.

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 mode constraint, but the long enumeration of return fields (titles variants, dimensions, provenance, entity-level authority triples, etc.) is bloated and largely duplicates the output schema, so several sentences do not earn their 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?

Complete enough to call correctly: input modes, exclusivity, examples, and exclusions are all present against a rich annotation and output-schema backdrop. The only overreach is re-explaining return values the output schema already owns.

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% (baseline 3), but the description adds real meaning beyond it: the mutual-exclusivity constraint 'provide exactly one of objectNumber or uri', a concrete example ('SK-C-5' for The Night Watch), and the note that uri comes from relatedObjects and can be exchanged with objectNumber (preferred).

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 with scope ('Full metadata for ONE artwork by objectNumber'), and explicitly distinguishes itself from the discovery siblings search_artwork, find_similar, and collection_stats. An agent can route to it 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 when-to-use (typically follows search_artwork / semantic_search / find_similar, or a user-named objectNumber) and when-not-to-use (not filter discovery, not similarity, not counts), each with the alternative tool named. Nothing is left to inference.

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 only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description adds the substantive behavior behind that: it opens a viewer for the user, may fail because not all artworks have images, returns metadata plus a viewer link rather than bytes, and warns against hand-constructing IIIF URLs. This is exactly the beyond-annotations context that annotations cannot carry.

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, then spends each following clause on a distinct failure mode (wrong request type, wrong tool, missing image, wrong expectation about return value). No filler and nothing repeated from 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?

For a 1-param tool with an output schema, all the failure modes an agent could hit are covered: usability exclusions, the sibling to use instead, image availability, and the exact nature of the return. 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 description coverage is 100% with a single documented parameter ('The object number of the artwork (e.g. 'SK-C-5')'), so the schema already carries parameter meaning. The description adds no further semantics about objectNumber (no format rules, no lookup guidance), making the baseline 3 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 ('Opens an interactive deep-zoom viewer') with a clear effect on the user's environment, and explicitly contrasts itself with siblings (inspect_artwork_image for bytes, list/summary/count requests). An agent can distinguish it from remount_viewer/navigate_viewer and the search/detail 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?

Gives explicit when-to-use ('when they ask to see, show, or view an artwork'), when-not ('not for list, summary, count, or text-only requests'), and a named alternative for the adjacent case ('use inspect_artwork_image to get image bytes'). Routing is unambiguous.

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-destructive behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: the concrete examination types returned, the treatment-event list, the signature count, and the crucial nuance that the mark count is a count only while transcriptions live in search_inscriptions.

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 one-line purpose, then the invocation context, then the return contents, then the three routing exclusions. Every sentence carries distinct information; nothing is padding.

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 the payload and wires the agent to the right sibling for each adjacent need. Nothing required to call 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% and the single parameter is fully documented with format examples in the schema itself. The description only restates 'by objectNumber', adding no syntax or constraint information beyond the structured fields, 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 and resource ('technical examinations and restoration history'), scopes it to exactly ONE artwork identified by objectNumber, and enumerates the returned content types. An agent can distinguish it from get_artwork_details and search_inscriptions 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?

Gives explicit when-to-use context ('Follows get_artwork_details / a search result, by objectNumber') plus three explicit exclusions naming the correct alternative for each ('Not for general metadata — use get_artwork_details', 'Not for transcribed inscriptions — use search_inscriptions', 'Not for aggregate counts — use collection_stats').

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral detail: results are paginated and anchored to a checkpoint, deleted records surface as deleted:true with only a LOD URI and datestamp, and identifiersOnly output omits objectNumber. It does not discuss rate limits or what a resumption token invalidates beyond filter-ignoring, which the schema covers.

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 core purpose, then layered detail on mode selection, follow-up calls, and deletion handling; nearly every clause carries operational information. It is on the dense side for four sentences but avoids 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 six-parameter paginated feed with an output schema present, the description supplies everything an agent needs that the structured fields don't: checkpoint anchoring, the identifiersOnly trade-off, and how deleted records appear in results. Return-value details are rightly 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, but the description adds meaning beyond the schema by explaining the functional consequence of identifiersOnly (headers only, no objectNumber, requires re-run to act) and the shape of deleted records. The remaining parameters (from/until/setSpec/maxResults/resumptionToken) are only echoed from 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?

States a specific verb+resource+scope: an OAI-PMH delta feed of records changed within a date range, anchored to a harvest checkpoint. This is clearly distinguishable from sibling search/browse tools because it is change-oriented rather than query-oriented, and it names the downstream tools (get_artwork_details, get_artwork_image) it feeds.

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 concrete routing guidance: use identifiersOnly=true for a lightweight listing and re-run without it when you need to act on a change, plus it names the follow-up tools keyed on objectNumber. It lacks an explicit 'when not to use this' (e.g., versus search_artwork for enumerating a corpus), so it falls just short of the top band.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: base64 payload, no upscaling past the region's own pixels, automatic viewer zoom with navigateViewer defaulting to true, and that the response carries cropPixelWidth/cropPixelHeight and the active viewUUID for follow-up calls. These are non-obvious side effects an agent needs.

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?

Purpose and the sibling routing are front-loaded, and later paragraphs cover regions and viewer side effects. It is a bit long with some overlap between the 'region' prose in the body and the schema description, but nearly every sentence carries actionable 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 7-parameter vision tool with an output schema and full annotation coverage, the description supplies the remaining context: cross-tool workflow (get_artwork_details for panel percentages, navigate_viewer for follow-ups), image-degradation behavior, and response fields. Nothing an agent needs to call it correctly is missing.

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

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 real meaning: the three region coordinate syntaxes and which to prefer, the rationale for the size ceiling, and that 'gray' quality helps read inscriptions or signatures. It does add value over the schema, though it largely echoes the parameter descriptions already present.

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 ('Returns image bytes (base64) for the LLM's own visual analysis') and immediately scopes what it covers: a whole artwork or a region. It actively distinguishes itself from siblings by naming get_artwork_image (interactive viewer) and search_artwork (listing/summarising) as the wrong tools for those jobs.

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 when-to-use and when-not-to-use: 'not for the user to view (use get_artwork_image)', 'Not for listing or summarising artworks — use search_artwork'. It also tells the agent when to use region 'full' versus a tight region (zoom into details, read inscriptions, examine specific areas), leaving little to inference.

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=false, so the safety profile is covered. The description adds real value beyond that: it enumerates what each result carries (memberCount, dominantTypes, dominantCenturies, category heuristic) and explains the umbrella-vs-subset behavioral distinction via set size, which is not inferable 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?

Dense but front-loaded: purpose first, then what results carry, then a usage tip, then exclusions. Every sentence carries information, though the packed middle sentence listing result fields is slightly heavier than the rest.

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 re-explained, yet the description still orients the agent to result shape and category values. Combined with the explicit sibling routing and min/max member guidance, 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 description coverage is 100%, so the baseline is 3, but the description adds operative guidance the schema lacks: specific minMembers/maxMembers values (100/200000) and the rationale (avoiding umbrella sets like 'Alle gepubliceerde objecten'), plus the category heuristic that helps interpret results.

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 ('Browse thematic sets curated by Rijksmuseum staff') and immediately scopes it by naming the sub-collection groupings and returned fields. It also names sibling tools it is not, so an agent can distinguish it from search_artwork, collection_stats and browse_set 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 gives when-to-use (browsing curated sets, paired with browse_set(setSpec) to enumerate members) and when-not-to-use ('Not for keyword search ... use search_artwork. Not for aggregate counts — use collection_stats'), plus a concrete minMembers/maxMembers tip (100/200000) to avoid umbrella sets.

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 only declare the mutation/idempotency profile; the description adds concrete behavior: out-of-bounds regions rejected with an overlay_region_out_of_bounds warning, batch limit under 10 commands, a 30-minute idle session timeout reset by polling, and the three deliveryState outcomes including guidance not to narrate queued as failure. This is substantial context beyond the structured fields.

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?

It is long, but front-loaded with the routing decision first, then coordinate formats, then response semantics. Nearly every sentence carries operational value; a small amount of the region-format list duplicates the schema wording.

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?

Complete for a command-batch mutation tool: prerequisites (viewUUID, viewer open), coordinate semantics, error handling, rate/batch limits, and delivery-state interpretation are all covered, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: default full-image coordinate space, the relativeTo exception, and a worked mapping showing the same pct string targets the same area in viewer and inspect_artwork_image. This goes beyond the schema text.

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 ('Zooms/pans an already-open viewer to a region') and explicitly names the two siblings it is not: get_artwork_image for opening, inspect_artwork_image for analysis. An agent can distinguish it from every sibling 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?

Gives explicit when-not guidance ('In most cases you do NOT need this tool') and the precise condition that selects it ('only to move the user's view WITHOUT fetching image bytes'). The alternatives are named with the case each covers.

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 declare readOnlyHint=false and idempotentHint=false, which is surprising for a tool whose name and description say 'poll', but the description never explains the side effect (e.g., that polling consumes/clears pending commands). With annotations present the bar is lower, yet the key behavioral question raised by the annotations goes unanswered.

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?

A single short sentence with the scoping qualifier ('Internal') front-loaded and no wasted words. It is efficient, though its brevity is partly the source of the missing context rather than pure economy.

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 described, but for a non-idempotent, non-read-only tool with an undocumented parameter, the definition leaves too much unstated. An agent cannot tell whether polling mutates state, how viewUUID is obtained, or when this tool should be invoked.

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 schema has one required parameter, viewUUID, with 0% description coverage, and the description does not mention it at all. The baseline-3 rule applies only when schema coverage is high; here the description must compensate and does not, so it falls below 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 ('poll') and resource ('pending viewer navigation commands'), and the 'Internal:' prefix signals this is an internal mechanism rather than an agent-facing action. It is distinguishable from siblings like navigate_viewer and remount_viewer, though it does not explicitly contrast itself with them.

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 'Internal:' marker hints that this tool is not meant for general use, but the description gives no explicit when-to-use guidance, no conditions, and no reference to navigate_viewer or remount_viewer as alternatives. An agent has to guess whether polling complements or replaces those 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 declare readOnlyHint=false but destructiveHint=false, and the description adds genuinely new behavioral context: an existing user highlight is cleared because its coordinates belong to the previous artwork, and the viewUUID is preserved across the switch. That side-effect disclosure goes beyond what the annotations convey; only the lack of failure/error behavior keeps it from 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 front-loaded sentences with zero filler: scope marker, invocation context, and the one non-obvious 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?

With an output schema present, return values need not be described, and the trigger plus the highlight-clearing effect cover the essential behavior. It is nearly complete for a narrow internal utility, missing only error/precondition behavior.

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% and both parameters are documented there (viewUUID provenance from get_artwork_image, objectNumber meaning). The description reinforces the preserve-viewUUID contract but adds no new syntax or constraint, 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?

The description states a specific verb+resource ('switch the viewer to a different artwork') plus the key constraint ('while preserving the viewUUID'), which distinguishes it from the sibling navigate_viewer. The 'Internal:' prefix immediately frames its scope, so an agent can tell what it does without opening the 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?

It gives a clear calling context: 'Called by the artwork-viewer iframe during in-viewer related navigation,' and 'Internal:' implies it is not meant for general agent use. It does not explicitly name an alternative (e.g. navigate_viewer) or state when not to call it, so it falls short of a 5.

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 read-only/idempotent annotations, the description discloses key behaviors: ranking switches between BM25 and importance, totalResults is the exact match count rather than the page size, array values are AND-combined, shared object-number prefixes trigger warnings, and compact=true skips detail resolution. It also states follow-up paths to get_artwork_details and get_artwork_image.

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 front-loaded with the tool's purpose, then alternatives, then ranking and filter behavior, so it is easy to scan. It is long for a 19-parameter tool, and a few sentences could be tightened, but most content earns its place by preventing misrouting or misuse.

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, 19 parameters, full schema coverage, and output schema, the description is complete enough for an agent to call it correctly. It covers routing, required conditions, ranking, filter semantics, return behavior, warnings, and follow-up tools without needing to explain the output schema in detail.

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 already 100%, so the baseline is 3. The description still adds cross-parameter meaning that the schema does not state per-parameter: array filters are AND-combined, sort overrides BM25 and geo-proximity ordering, and subject has the highest recall for concept searches while description and curatorialNarrative cover different corpora.

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: 'Structured filter search — artworks matching ALL given filters.' It immediately distinguishes itself from semantic_search, find_similar, search_persons, search_provenance, and collection_stats, so an agent can route correctly without opening the 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 gives explicit when-to-use and when-not-to-use guidance: 'Not for free-text concept queries — use semantic_search for those,' 'Not for artwork-to-artwork similarity — use find_similar,' and it routes demographic queries to search_persons first and provenance queries to search_provenance. It also explains required conditions such as 'At least one filter is required' and 'There is no full-text search across all metadata.'

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