Artlist — Czech contemporary art archive

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds value beyond them by disclosing the content the call returns — schema-level concepts, language coverage, record counts and search advice — which matters because there is no 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?

Two short sentences with zero filler; the imperative 'Call this first' is front-loaded ahead of the content inventory. Every clause earns its place by telling the agent either when to call or what it will learn.

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 zero-parameter, read-only orientation tool with no output schema, the description supplies both the trigger and the expected return content. Nothing further is needed for an agent to invoke it correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing parameter-level for the description to compensate for. No misleading or missing argument information is 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?

The description names a specific verb ('Explains') and enumerates exactly what is explained: record types, public fields, record linking, languages, record counts and search strategy. That enumeration separates it cleanly from the sibling tools (artlist-search, artlist-get, artlist-related, artlist-facets), which operate on data rather than document it.

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?

'Call this first' gives explicit sequencing guidance relative to every sibling tool, which is the key decision an agent faces here. It stops short of stating when the tool can be skipped (e.g. on repeat calls within a session), so it is clear context rather than full when/when-not coverage.

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 safety is covered structurally. The description adds that the output is aggregated counts/distributions rather than records, which is useful, but says nothing about cost, cardinality, or whether results respect any default filters.

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 short, but the single semicolon-and-colon-stitched sentence is hard to parse and buries the more important conditional behavior mid-string. Restructuring into one sentence per mode would cost no extra words and be far clearer.

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 no output schema, the description must carry the return shape, and it does so only at a coarse level: the described sections (decades, topics, places) are not stated to be returned together with their key names or ordering, and the relationship between the no-`type` and `with type` result shapes stays fuzzy.

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, and the description exceeds it by explaining the conditional effect of `type`: omitting it yields counts per type/language plus top topics, whereas supplying it switches to a decade distribution, per-type topics and common places. That conditional-output semantics is not derivable from the enum alone.

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 the resource is aggregate statistics (record counts per type/language, top topics, and per-type breakdown by decade, topics, places), which is broadly distinguishable from artlist-get/search. But the phrasing is a noun fragment with no verb, and the pivot 'with type:' is ambiguous about what condition triggers the second behavior, so the purpose is only partly clear.

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?

'Good for overviews and for choosing filters' gives an implied when-to-use, and the two modes hint at when to supply `type`. No sibling is named and there is no explicit when-not guidance (e.g. use artlist-search to fetch actual records rather than 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral detail: truncation at 5000 chars unless full=true, images collapsed to image_count unless images=true, and linked records grouped by type. What it omits is failure behavior — what happens if neither id nor url is supplied, since all four parameters are optional.

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 purpose, then progressively discloses return shape and the two truncation switches in three tight sentences. Dense but no filler; the trailing "For a contributor:" clause is the only slightly bolted-on element.

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 no output schema, the description carries the full burden of describing the response, and it does so section by section, including the truncation defaults an agent must know about. The only gap is the ambiguity of zero required parameters — it never says id and url are mutually exclusive or which wins when neither is given.

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 earns more by explaining the actual consequences of the flags: full=true restores long texts, images=true expands image_count into URLs, captions and copyright, and id/url are interchangeable identifiers. That is meaning beyond the one-line schema strings.

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?

"Full public record by id (or page url)" states a specific verb and resource, and the enumeration of returned sections (biography, exhibitions, bibliography, linked records, language versions) makes clear this is the detail endpoint rather than a list. Sibling differentiation is implicit rather than stated — it never names artlist-search or artlist-describe as the alternative path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Record id from search results" in the schema and the by-id-or-URL framing imply this is the follow-up call after a search, and the contributor note hints at a second use case. But there is no explicit when-to-use/when-not guidance and no mention of artlist-related or artlist-describe as alternatives for linked or summary data.

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 and idempotent annotations, the description explains that topics mode returns shared_topics, links depth=1 returns direct links such as works, groups, and videos, and depth=2 returns records connected through a shared neighbour ranked by shared link count. It adds meaningful behavioral context, though it does not fully describe the return shape or pagination behavior.

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 and front-loaded with the core purpose, then moves directly into mode-specific and depth-specific behavior. Every sentence carries useful information, and the examples are efficient rather than verbose.

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 exploration tool with annotations covering safety and a schema covering every parameter, the description supplies enough behavioral detail for an agent to choose between links and topics and to understand depth=1 versus depth=2. It is slightly incomplete on return shape and how lang, limit, and types affect results, but those are documented in the 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 schema already documents the parameters, but the description adds meaningful semantics for the key parameters via and depth, including defaults and concrete depth=2 ranking behavior. It does not elaborate on lang, limit, or types beyond the schema, but it substantially clarifies the most consequential parameters.

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 that this retrieves records connected to a given record and distinguishes the two connection modes, links and topics. It does not explicitly contrast itself with sibling tools such as artlist-get or artlist-search, so it stops short of full sibling differentiation.

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 clear conditions for choosing via="topics" versus via="links" and explains what depth means in the links mode with concrete examples. It does not explicitly say when to use this tool instead of sibling retrieval or search tools, so usage guidance is strong but not complete.

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, and the description adds real substance on top: accent-insensitive matching, all-words-must-match semantics, quote-delimited phrases, year filtering as range overlap rather than containment, and pagination via offset/next_offset. It also discloses the shape of the returned records (id, type, name, years, summary, url) even though no output schema 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?

Three dense sentences, front-loaded with the capability and followed by matching rules, output shape and pagination — no filler. The opening enumeration of record types largely restates the types enum, and the 'events' label is a small inconsistency that costs a point.

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 13-parameter, zero-required search tool with no output schema, the description covers the essentials: matching rules, filter semantics, return fields, and paging. The residual gap is the type-name mismatch ('events' vs 'post') and no hint about how multiple filters combine (AND vs OR) beyond what individual params say.

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 92%, so the baseline is 3; the description earns an increment by stating cross-parameter semantics the schema cannot express — that year_from/year_to are an overlap test on activity dates, that query matching is accent-insensitive and conjunctive, and that quoted strings become phrase queries. The only weakness is that the prose type list says 'events' while the types enum offers 'post', a small mapping the agent must infer.

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?

Opens with a concrete verb ('Find') and enumerates the resource domain (artists, theorists, groups, spaces, artworks, videos, annotations, contributors) plus the two search modes (free text and filters). It also explicitly contrasts itself with the sibling artlist-get, so an agent can place it 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?

It routes the agent onward in both directions: 'use the get tool (artlist-get) for details' for full records, and 'See facets for the list' for valid topic names (i.e. artlist-facets). It does not explicitly say when to prefer this over artlist-related or when a filter combination is inappropriate, so it falls just short of full when/when-not 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that it returns full text, all public fields, linked records, annotations, and a page URL for citation.

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 a single, front-loaded sentence with no redundant wording. It communicates the core action and return contents efficiently.

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 low complexity (one required id parameter), the existing output schema, and the annotations covering safety, the description is complete enough for an agent to select and call the tool correctly. No critical missing information is apparent.

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 id parameter already has a clear schema description ("Record id from search results."). The tool description reinforces that the id comes from search but adds no additional syntax or format details 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 states a specific retrieval action: "Full text of one Artlist record by id from search," and enumerates what is returned (public fields, linked records, annotations, page URL). It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools such as artlist-get or search.

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 phrase "by id from search" implies this tool should be used after a search returns a record id, giving some usage context. However, it does not explicitly say when to use this versus artlist-get or other siblings, nor does it state exclusions or prerequisites.

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, and the description adds the useful note that results are ids requiring fetch. It says nothing about result limits, language-mixing behavior, or match semantics, which would be the genuinely additive details beyond 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?

Three short clauses: scope, return shape, and the alternative for filtered queries. Front-loaded with the resource and archive, zero filler, and the routing hint comes last where it belongs.

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 explained, and one fully documented parameter is trivial to cover. The description supplies the two things the structured fields cannot: domain scope and the ids-then-fetch workflow, though it omits result-count or pagination expectations.

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% with a single required "query" parameter already documented as "search text, e.g. a name, technique, place or topic." The description reinforces the breadth of entity types but adds no syntax, matching, or normalization guidance beyond the schema, so 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 and resource ("Standard document search over the Artlist archive") and enumerates the entity types searched, so the agent knows what it returns (ids for fetch). It differentiates itself from artlist-search only indirectly, by calling itself "standard" and pushing filters elsewhere, which is slightly muddier than a clean sibling split.

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 routing rule: use this for plain queries, prefer artlist-search when filters (type, years, topics, links) are needed. That is an explicit alternative with a condition, though it does not mention when not to use search at all versus fetch or artlist-get by id.

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