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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations, notably that protected full texts (Dodis transcriptions) are not reproduced and the response links to the permalink instead. It also discloses the response format options (markdown/json), improving transparency.

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 and well-structured, using an Args/Returns layout. It front-loads the main action, adds a key caveat, and lists parameters in a compact way. Every sentence contributes value without 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?

The description covers the core functionality, supported collections, output contents, protected-text behavior, and response formats. Minor gaps include no mention of error handling or default response_format, but given the presence of annotations and an output schema, the overall context is adequate for correct tool usage.

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?

Despite the schema description coverage being 0%, the description's Args section summarizes all three parameters (collection, item_id, response_format) with their valid values and clarifies that item_id originates from search_heritage. While it omits the schema's concrete examples, it provides a functional overview that helps the agent understand parameter roles.

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: 'Ruft die vollständigen Metadaten eines Objekts aus Memobase oder Dodis ab.' It clearly distinguishes itself from sibling search and list tools by targeting single-object metadata retrieval, and further specifies that it returns permalink, license, provenance, and a caveat about protected full texts.

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 implies the expected workflow by stating that item_id comes from 'search_heritage', which gives clear context for when to use this tool. However, it does not explicitly name alternative tools or provide exclusion criteria (e.g., 'don't use for full-text extraction'), so it falls just short of full explicit 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=true, idempotentHint=true, and destructiveHint=false, so the description's addition of return format and prerequisite adds context but does not significantly extend beyond what annotations imply. No behavioral aspects like rate limits or auth are mentioned, but annotations suffice.

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?

Structured with a concise intro, prerequisite line, bullet-pointed args, and returns line. Every sentence is purposeful and front-loaded with the main action. No wasted words, appropriate length.

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 rich annotations and an existing output schema, the description covers the prerequisite, input parameters, and return format. It explains pagination via limit/offset and response_format choices. It feels complete for a browsing tool, with no missing critical information.

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?

Description adds value beyond the schema by listing parameters with examples (e.g., query: 'Zürich', 'Karl der Grosse', 'Gold') and clarifying the prerequisite for resource_id. Although schema coverage is 0%, the description compensates well by explaining each parameter's purpose and usage.

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?

Description clearly states it searches objects within an SNM collection dataset via CKAN DataStore. The verb 'Durchsucht' and specific resource 'Objekte innerhalb eines SNM-Sammlungsdatensatzes' provide clear purpose. The prerequisite for resource ID from heritage_search_museum_datasets further distinguishes it from sibling tools like heritage_cross_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?

Explicitly states the prerequisite of having a resource ID from heritage_search_museum_datasets, guiding when to use this tool. However, it does not explicitly state when not to use it or provide alternative tools for similar tasks, though sibling names give implicit context.

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?

Adds behavioral traits beyond annotations: progress reporting, warning on failures, fan-out latency. Consistent with readOnlyHint=true.

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?

Well-structured with paragraphs and Args/Returns sections; concise but covers all essential details without 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?

Covers purpose, behavior, parameters, and return type. However, no output schema is provided, and the return type is only briefly mentioned.

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?

Despite schema coverage 0%, the description lists parameters with types, defaults, and example values (e.g., 'Suchbegriff', sources list), adding meaning beyond 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 clearly states it searches SIK-ISEA, SNM, and NB simultaneously, distinguishing it from single-source sibling tools like heritage_search_artists or heritage_search_helveticat.

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 implies use for cross-source queries but does not explicitly state when to avoid or alternatives; however, the context of searching multiple sources 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 declare readOnly, idempotent, non-destructive. Description adds return value details (profile with life data, places, biography, links). No contradictions.

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?

Description is well-structured with Args and Returns sections, but could be slightly more front-loaded. No fluff, but the bullet list could be more compact.

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 simple nature (one parameter object with two fields), annotations, and presumed output schema, the description covers everything needed: input usage, return format, and data included.

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?

Despite schema description coverage at 0%, the description clearly explains both parameters: artist_id cross-references sibling tool, and response_format lists possible values with default. Adds meaning beyond 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?

Description clearly states it retrieves the complete SIKART dataset for an artist. Distinguishes from sibling 'heritage_search_artists' which is for searching, as this tool takes a specific ID to get full details.

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 notes the prerequisite: artist_id from heritage_search_artists. Does not provide when-not or alternatives, but context is sufficient for a simple retrieval tool.

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 and idempotent, but the description adds substantial behavioral context: the source is MARCXML, the output is a selective Dublin-Core-like mapping, and it explicitly lists excluded fields such as MARC 250, control fields, and local fields. The warning not to interpret the response as the complete catalog record is particularly valuable.

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 relative to the ground it covers: purpose, field selection, exclusion list, and docstring-style Args/Returns sections. Every sentence earns its place, and the most important misuse risk—treating the result as the full catalog record—is clearly emphasized.

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 read-only retrieval tool with one required identifier plus an optional format, the description is complete: it states the input provenance, the output mapping, the excluded fields, and the fallback for full metadata. Since an output schema exists, the absence of a detailed return schema is not a gap.

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 Args block names both parameters and restates what the embedded schema already provides: identifier is the OAI-ID from heritage_search_helveticat and response_format is 'markdown' or 'json'. It adds no new parameter-level semantics, such as how the markdown and json outputs differ, so it meets the baseline but does not exceed it.

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 concrete operation: 'Ruft die Metadaten einer Publikation der NB ab' and immediately scopes it to 'ausgewählte MARC21-Felder'. It also explicitly distinguishes the result from a full catalog record, making it easy to separate from sibling search tools.

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 implies the right entry point by saying the identifier comes from heritage_search_helveticat, and it gives a clear alternative for full metadata: 'Wer den braucht, nimmt den Permalink aus identifier und geht an die Quelle.' It does not enumerate all sibling tools, but for its scope the guidance 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, indicating no side effects. The description adds that the tool performs an OAI-PMH ListSets request and returns a list with setSpec and name, which is useful but does not significantly enhance the behavioral profile beyond what annotations provide. No contradictions.

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 with a clear one-sentence purpose followed by structured Args and Returns sections. It front-loads the main action and avoids fluff. The total length is appropriate for the tool's simplicity.

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 description covers the input parameter and return format comprehensively for a simple list tool. It mentions the output contains setSpec and name. However, it lacks details on pagination, if applicable, or sample output. Given the tool's low complexity and presence of an output schema (per context), the description is nearly complete.

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 descriptions for NbCollectionsInput and ResponseFormat, but context indicates low schema coverage. The description adds the default value and explains that response_format can be 'markdown' (default) or 'json'. This is helpful but largely redundant given the schema's enum and default. With only one parameter and schema already providing structure, the description adds marginal value.

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 the tool lists available collections/sets of the national library via OAI-PMH ListSets. It specifies the verb 'listet' (lists) and the resource 'Sammlungen/Sets der Nationalbibliothek', making the purpose unambiguous. This distinguishes it from sibling tools like 'heritage_browse_collection' which likely explores a specific collection.

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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, use cases, or exclude scenarios. While the sibling tools offer browsing, searching, and retrieval, the description fails to explicitly differentiate usage, leaving the agent to infer from tool names.

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?

Discloses full-text search, AND combination, automatic fuzzy fallback, and match_type markers. Annotations already indicate readOnly and idempotent, so the description adds value beyond that.

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?

Efficient structure: purpose sentence, data source, search mechanics, then bullet-point Args, and Returns. No wasted words; front-loaded with key action.

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 (search, fallback, pagination, output format), the description covers all aspects including return format and examples. Output schema is described in the 'Returns' section.

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 description lists each parameter with meanings and examples (e.g., 'Hodler', 'Basel') Add meaningful context beyond the schema, which has descriptions but context signal indicates 0% overlay coverage.

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 it searches for Swiss artists in the SIKART database using a specific verb ('Sucht') and resource. It distinguishes from sibling tools like heritage_get_artist (single artist) and heritage_search_helveticat (library catalog).

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?

No explicit guidance on when to use this tool versus alternatives like heritage_cross_search or heritage_get_artist. The description focuses on search mechanics but omits situational advice.

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/openWorldHint/idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds genuinely valuable behavioral context beyond that: the one-time loosened fuzzy retry marked as match_type: fuzzy, the pagination semantics of OAI-PMH (query filters only within the fetched page), and the measured incompatibility of the two protocols. This is rich additional disclosure, though the date-parameter caveat partly lives in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is dense but every sentence earns its place: purpose, two-mode bullet list, the bolded measured-split rationale, then a compact Args list and Returns line. It is front-loaded with the purpose and scannable via bullets. Only modest over-length from the appended protocol-comparison paragraph, which is justified by the tool's genuine 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 combining two protocols with conditional parameters, a fuzzy retry, date-semantics caveats, and an output-format choice (markdown/json), the description covers purpose, both usage paths, param constraints, and return shape ('Liste von Publikationen mit Titel, Autor, Jahr, Schlagwörtern und Identifier'). It is near-complete; the only minor gap is no explicit statement of how the markdown vs json output differs.

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 description's Args section adds key interaction semantics the schema alone cannot convey: query is a server-side full-text search WITHOUT set_spec but only filters within the fetched page WITH it; from_date/until_date apply solely with set_spec. While the schema properties do carry their own descriptions, the conditional relationships and the two-protocol branching are unique to the description. Strong compensation despite the 0% schema-coverage signal.

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 line 'Durchsucht die Schweizerische Nationalbibliothek (Helveticat)' names a specific verb, resource, and institution. The description then distinguishes two concrete access modes (SRU full-text vs OAI-PMH collection browse), and explicitly references the sibling heritage_get_publication for consuming results — clearly differentiating it from siblings like heritage_search_artists and heritage_browse_collection.

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 guidance for each mode: 'query ohne set_spec' → SRU full-text search, 'set_spec' → OAI-PMH collection browse, and explains why they are not interchangeable ('SRU kennt die OAI-Sets nicht... OAI-PMH kennt keine Volltextsuche'). It names the alternative heritage_get_publication for fetching results and heritage_list_nb_collections for obtaining set specs. 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 already mark readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral detail: automatic query relaxation to OR wildcards on zero exact hits and fuzzy marking. No contradictions.

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 with clear sections: purpose, data scope, special behavior, args, returns. It is concise and informative, though the fuzzy matching detail could be integrated more tightly. No wasted sentences.

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 presence of an output schema, the description adequately covers all necessary aspects: tool purpose, data source, query behavior, parameter details, and return format. It is complete for agent invocation without additional 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?

Despite schema coverage of 0% in the description, the text includes a detailed args section explaining each parameter's purpose, type, and examples (e.g., 'query' searches title/description, 'collection' filters like 'numismatik'). This adds significant meaning beyond the schema 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 clearly states the verb and resource: 'Sucht Datensätze des Schweizerischen Nationalmuseums auf opendata.swiss', specifying the exact domain and data source. It differentiates from siblings like heritage_browse_collection by focusing on cross-collection search via opendata.swiss, though not explicitly.

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 provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or compare with sibling tools like heritage_cross_search. Usage context is implied but not explicit.

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=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining that the tool lists status, protocols, auth, licenses, and even discloses deliberately non-connected sources with reasons. This goes beyond the annotation flags and gives the agent a realistic picture of the tool's output scope.

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 well-structured: a front-loaded purpose sentence, a discovery context sentence, a note about excluded sources, and a structured Args/Returns block. Every sentence contributes useful information, with no redundancy or 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 an output schema present and a moderate complexity, the description covers the essential aspects: purpose, usage relationship to sibling tools, parameter options, and return content (ResultEnvelope | str with collections/status/protocol/auth/licenses). It does not discuss error cases or format details, but overall it is complete enough for reliable selection and invocation.

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?

Despite schema description coverage of 0%, the description compensates by documenting the params structure: HeritageCollectionsInput | None, with response_format accepting 'markdown' (default) or 'json'. It adds meaning beyond the raw schema by stating the default and the allowed values. However, it does not explain what the markdown vs. json output looks like, which is a minor gap.

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+resource claim: 'Listet die Gedächtnisinstitutionen der föderierten Fassade und ihren Status auf.' It further distinguishes itself from siblings by positioning it as a discovery tool for search_heritage/get_heritage_item and specifying what it reveals (collection values, protocol, auth, license). This clearly separates it from the sibling list tools like heritage_list_nb_collections.

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 explicitly states when to use the tool: as a Discovery-Tool for search_heritage and get_heritage_item, to enumerate available collection values and their protocols/auth/licenses. It also explains that non-connected sources are included with reasons. It lacks an explicit 'when not to use' statement but provides sufficient context for appropriate selection.

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?

Even with annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral detail: parallel federated search, partial failure tolerance with error reporting via meta.errors and ctx.warning, separate metadata/digitization licenses, and the explicit statement that only metadata and links are returned—no protected full texts. It also explains client-side filtering and its impact on result counts, which is valuable beyond 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: a clear one-liner opening, followed by paragraphs on federated behavior, hit details, client-side filtering, Args, and Returns. It front-loads the purpose and uses headers/bullets effectively. It is somewhat longer than strictly necessary because the Args section partially duplicates schema information, but the additional context earns its place, so it remains appropriately concise.

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 complex federated search tool with multiple parameters and edge cases, the description is complete. It covers error handling, licensing, client-side filtering, pagination, and the output format (ResultEnvelope | str). The presence of an output schema means detailed return values are not needed, but the description still states that results include provenance. This is a thorough and self-sufficient description.

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 description includes an 'Args:' section that covers all parameters and adds meaning beyond the schema. For example, it specifies that date_from/date_to and media_type are applied client-side, that limit/offset paginate per source, and that ctx is injected by the MCP SDK. The schema itself has basic descriptions, but the description enriches them with behavioral context and clarifies the federated semantics.

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 starts with 'Durchsucht Schweizer Gedächtnisinstitutionen (Memobase, Dodis) föderiert,' which clearly states the verb (searches), resource (Swiss memory institutions), and scope (federated across Memobase and Dodis). It is specific, but it does not explicitly differentiate itself from sibling tools like heritage_cross_search or heritage_search_helveticat, so it stops short of a 5.

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 provides clear context for when the tool is appropriate: it searches specific sources (Memobase and Dodis), and explains the default behavior for collection='all' including failure tolerance. It also notes that date and media type filters are client-side, which guides expectations. However, it does not explicitly mention alternatives or 'when not to use' this tool, so it lacks the exclusionary guidance needed for a 5.

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