Balthasar & Speyr Catalogue

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 safety profile is covered. The description adds useful behavior beyond annotations: 'Results are paginated' and 'counts must not be summed across overlapping groups.' These disclose edge-case behavior and response traits that the agent needs to know.

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 at three sentences, front-loading the core purpose. However, the third sentence about 'Edition dimensions' is unclear and potentially confusing, though it is not redundant. The structure is efficient overall.

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 (6 top-level params, one required, a large nested filters object, no output schema), the description is far too thin. It does not explain the meaning of dimensions, how pagination works (page vs offset), what the response looks like, or how filters interact with grouping. The caveat about overlapping groups is helpful but leaves the agent guessing on essential details needed for correct 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?

Schema description coverage is 0%, so the description must compensate for missing parameter explanations, but it hardly does. It mentions 'up to two dimensions' (matching groupBy) and 'Edition dimensions' (a concept not even present in the enum values), but ignores page, offset, filters, pageSize, periodYears, and the complex filters object. The 'Edition dimensions' remark is cryptic and could mislead, as no enum value is called 'edition'.

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 action—'Group distinct works by up to two dimensions'—and identifies the resource (works in a catalog). It clearly distinguishes this from list/search operations by focusing on grouping and aggregation. The title 'Compare catalogue groups' is vaguer, but the description adds enough specificity to understand the core function.

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 usage when grouping works is needed, but it does not explicitly state when to choose this over siblings like count_catalog or list_works. There are no alternatives referenced, nor any conditions where this tool should not be used. The caveats about edition dimensions and pagination give partial usage context but no direct comparison with other tools.

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

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

Annotations already declare the operation read-only and idempotent. The description adds useful behavioral context beyond those annotations: it counts only public works, returns distinct counts, supports combined filters, and explicitly returns no bibliography or text. This is meaningful behavioral disclosure for a read-only aggregate tool.

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 sentences with no filler, and the core purpose is front-loaded. The most important constraints—public scope, distinct counting, combined filters, and no content returned—are stated economically.

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?

Despite a highly complex nested filters schema, no output schema, and zero parameter descriptions, the description explains only the general counting behavior and two filter fields. It does not describe the return shape or clarify the semantics of many filters, so an agent would still face significant uncertainty when constructing a correct call.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining the large filters object, but it only highlights baselReferences/baselReferencePrefix as exact-match filters and says filters can be combined. Many opaque parameters such as 'full', 'includeSemantic', 'hasExtractedText', and 'journalScope' remain unexplained, leaving significant semantic gaps.

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 a specific verb ('Count') and explicit resources ('distinct public works, editions and journals'), which precisely identifies the operation. It further distinguishes itself from retrieval tools by stating that no bibliography or text is returned.

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 makes clear that this tool is for counting, not content retrieval, and that filters can be combined. However, it never explicitly contrasts it with sibling tools like aggregate_catalog, list_works, or search_works, leaving the agent to infer when this is the right choice.

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 and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by noting that results depend on configuration ('recognized and enabled' and 'Corpus expansion is configuration controlled'), which tells the agent not to expect a static, fixed list.

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 sentences, both substantive: the first enumerates the returned data categories, and the second adds a meaningful configuration caveat. No wasted words, and the core functionality is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool, the description is nearly complete: it explains what data is returned and warns that configuration affects results. It does not describe the exact output format, but given the low complexity and rich annotations, this is not a significant 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?

There are zero parameters and the input schema is empty with 100% schema description coverage, so the schema already fully accounts for invocation. The description adds no parameter-specific detail, but none is needed, making the baseline 4 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the operation ('Get') and the exact resource: recognized and enabled types, authors, language codes, and public subject labels. This enumerated set differentiates it from sibling tools like get_corpus_coverage or list_publications without needing to inspect their schemas.

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

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

The description implies it should be used when callers need available catalogue filter options, but it does not explicitly state when to prefer it over alternatives or mention any exclusions. Context is clear enough, but no sibling differentiation or 'when not to use' guidance is provided.

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 that the tool is read-only, idempotent, non-destructive, and closed-world. The description adds meaningful behavioral context beyond those annotations: it returns exact Spanish passages and does not summarize or infer, which clarifies the nature of the response and guards against interpreting the output as interpretation.

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 sentences with no filler: the first states the deliverable precisely, and the second draws a clear boundary. The key scope information is front-loaded before the behavioral caveat.

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 input schema (one optional enum parameter), the rich safety annotations, and no output schema requirement, the description is complete. It tells the agent what will be returned, in what language, and what will not be done, so an agent can select and invoke the tool 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 schema has no descriptions for the single 'topic' parameter, so the description must compensate. It partly does by listing encounter, common work, and mission, which correspond to the enum values, but it does not explain the parameter itself, the default of 'all', or how to select among these topics.

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 ('Return') and a precise resource: exact Spanish passages about the encounter, common work, and shared mission of Balthasar and von Speyr. It names both persons and the collective scope, which distinguishes it from the sibling get_person_life_and_mission.

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 when to use it: when exact source passages are needed rather than summaries or inferences. It also explicitly says what the service does not do, which helps avoid misuse, but it does not name any alternative tool or provide explicit when-not-to-use conditions.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds meaningful behavioral context: it returns exact passages, includes existing related-text links, and explicitly states the service does not summarize or infer. This helps an agent set correct expectations about output fidelity.

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, delivering the core purpose in the first sentence and adding one critical behavioral caveat in the second. Every sentence earns its place with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one optional enum parameter and strong annotations, the description covers the return style and content scope. It does not explain the 'all' default or precisely define 'related-texts', but the schema provides the default, and the tool's low complexity makes the description reasonably 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?

Schema description coverage is 0%, so the description must compensate. It lists several enum values ('identity', 'consecrated-life', 'patrons', 'prayer', 'mission') and hints at 'related-texts' via 'existing related-text links', but it does not explicitly define all possible values such as 'all' or clarify the meaning of 'related-texts' as a topic choice. Some guidance is present, but the mapping is incomplete.

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 ('Return') and resource ('Community of Saint John') and enumerates the exact content domains covered. It clearly distinguishes this tool from siblings like get_common_life_and_mission or get_person_life_and_mission by identifying the unique subject and the exact-passage behavior.

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 clear context: use this to retrieve Spanish passages about the Community of Saint John's identity, consecrated life, patrons, prayer, and mission. It does not explicitly name alternative tools or exclusion criteria, but the scope is specific enough that an agent can infer when this tool is appropriate.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds value by explicitly stating 'unavailable text is not evidence of absence', which is a natural-language disclosure of the openWorldHint=false semantic. This interpretive guidance goes beyond simply repeating annotation flags and helps agents avoid a common reasoning error.

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 sentences with zero filler. The core purpose appears first, and the usage caveat earns its place. No unnecessary detail or repetition of annotations or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite clear purpose and a useful usage tip, the tool has no output schema, zero parameter documentation, and a highly complex nested filter object. The description does not say what the response looks like, whether filters are required, what the default behavior is, or how exclusions are represented. For an agent to invoke this correctly, much more context is needed.

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

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

Schema description coverage is 0%, so the description must compensate. It only says 'under bibliography filters', which is a vague high-level hint, and mentions author and original language as dimensions without explaining the nested filter object's fields, constraints, or construction. With over 20 undocumented filter properties, this is grossly insufficient for an agent to confidently populate the parameter.

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: 'Get coverage and exclusions by author and original language'. It distinguishes itself from siblings like count_catalog or list_works by focusing on coverage/exclusions rather than raw counts or item lists, and the title 'Check catalogue and text coverage' reinforces the purpose clearly.

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 instruction 'Use before comparisons' gives a clear, actionable trigger for when to call this tool, and 'unavailable text is not evidence of absence' warns against misinterpreting results. It provides clear context without explicitly naming alternative tools, so it falls just short of a full 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?

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful context beyond those: it resolves verified source corrections, optionally checks availability, and does not generate files. This clarifies expected behavior and side effects without contradicting the annotations.

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

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

The description is compact and front-loaded with the core action: 'Get existing download links.' The subsequent clauses add necessary distinctions without redundancy. No filler or repeated structured 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 simple read-only tool with robust annotations, the description is largely adequate, but key context is missing: there is no output schema and the description does not explain what 'resolves verified source corrections' means for the returned data or what 'checking availability' entails. These ambiguities make it less than fully 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?

Schema description coverage is 0%, so the description must compensate. It explains checkAvailability indirectly via 'optionally checking availability,' but publicationId is only inferable from the tool title and context, and no additional semantic detail about parameter values or output is provided. Partial compensation for a low-coverage 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 verb and resource: 'Get existing download links.' It also clarifies what the tool does not do ('Does not generate files'), which distinguishes it from potential generation-like tools. The resource is clear and the behavior is specific enough to separate it from siblings like get_publication_text.

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?

Usage is implied: use this tool when you need existing download links for a publication. The description provides one exclusion ('Does not generate files') but does not name alternative sibling tools or offer explicit when-to-use versus when-not-to-use guidance relative to the other publication-related tools.

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

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

Annotations already signal readOnly and idempotent behavior; the description adds value by guaranteeing exact Spanish passages, including common-mission evidence under the mission topic, and explicitly refusing summarization or inference. No contradiction with annotations.

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

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

Three sentences with no filler. The core behavior is front-loaded, and every clause adds information: exact Spanish passages, named persons, common-mission inclusion, and no summarization/inference.

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?

Sufficient for basic invocation with a person, but the boundary against get_common_life_and_mission is ambiguous due to the shared 'common-mission evidence' language. Since there is no output schema, a brief note on return format or sibling distinction would improve completeness.

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 ties the output to the two person values and adds nuance to the mission topic by mentioning common-mission evidence. However, it does not explain the topic parameter's optionality/default ('all') or enumerate the other topic values, leaving the schema enums to carry that weight.

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 ('Return'), resource ('exact Spanish biographical and mission passages'), and subject ('for Hans Urs von Balthasar or Adrienne von Speyr'). The disclaimer 'does not summarize or infer' narrows the contract and differentiates it from synthesis/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?

No explicit 'use when' or alternatives are given. The exact-passages/no-summarize language implies use when raw evidence is needed, but the description never names siblings like get_common_life_and_mission or search_life_mission_and_community, nor states when not to use them.

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, destructiveHint=false, so the safety profile is covered. The description adds that the tool is paginated and that full texts are not included, which is useful behavioral context. It doesn't mention default pagination size, max page size, or that facets can be requested, but those are visible in the schema. No contradiction with annotations.

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

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

Two sentences, front-loaded with the main purpose and key filters, then pagination and the sibling routing. Every sentence earns its place. Slightly dense with filter names but still efficient.

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 read tool with 0% schema coverage and no output schema, the description is adequate but has gaps. It tells the agent this is a paginated detailed-record getter and routes full-text needs elsewhere. But it doesn't explain the facets parameter, the meaning of 'detailed' vs list_publications, or what the response contains. Given the tool's complexity (nested filters, 7 top-level params), more context would help an agent select and 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It names publicationIds, workTypes, and publicationTypes as filter dimensions, which adds some meaning. However, the schema has 7 top-level parameters and a large nested filters object with ~25 properties; the description only hints at a few. It doesn't explain what 'facets' does, what sortBy options mean, or how pagination parameters interact. Baseline 3 is appropriate because the description adds some value but doesn't compensate for the 0% 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 states a specific verb ('Get') and resource ('detailed publication records'), and names the key filter dimensions (publicationIds, workTypes, publicationTypes). It distinguishes itself from get_publication_text by noting full texts are handled there. However, it doesn't explicitly differentiate from list_publications, which is a close sibling, so it's clear but not fully differentiated.

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 clear context: use this for detailed records, paginated, and full texts go to get_publication_text. It doesn't explicitly say when to use list_publications instead, but the 'detailed' qualifier and the explicit routing to get_publication_text provide useful guidance. No exclusions are stated, but the context is clear enough.

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 indicate a safe, read-only, idempotent operation. The description adds valuable behavior beyond that: the pagination contract, the fact that results include source URL/format/locators, the caveat that publication.text is not assumed complete, and the collective-source interpretation. No contradiction with annotations.

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

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

The description is compact and front-loads the main action in the first sentence. The later sentences about completeness and collective source are dense but informative; they could be more concrete, yet they do not waste the reader's time.

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 tool with no output schema, the description gives enough orientation: what is read, pagination behavior, and what the response includes. It does not document input parameters or exact response shape, but the schema's types/defaults plus the description's trail are sufficient for correct 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?

Schema description coverage is 0%, so the description needed to compensate for the three parameters. It only indirectly references pagination via 'nextOffset' and never explains publicationId, offset, or limit semantics. The ordered-sections phrase hints at offset usage, but the parameter meanings are largely left to the agent's inference.

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: 'Read the downloadable EPUB/PDF text in ordered sections.' It clearly differentiates this from siblings like search_publication_text by framing it as reading full text in ordered sections, and clarifies the scope with 'not necessarily one contained work.'

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 an explicit usage instruction: 'Continue using nextOffset until null,' which tells the agent how to paginate through the complete text. It does not explicitly name alternatives or when-not-to-use cases, but the reading-oriented context makes the tool's role clear relative to search siblings.

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 that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: results are 'bounded', topic assignments are 'precomputed', filtering is supported, and pagination should continue using 'nextOffset'. No contradiction with annotations.

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

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

The description is compact and front-loaded with purpose, then filtering capability, then pagination guidance. Each sentence earns its place, though the phrasing is terse and could be slightly 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?

Given the very large nested filter schema and no output schema, the description is incomplete. It does not explain what evidence the response contains, how filters interact, or how pagination with 'nextOffset' maps to the request parameters. An agent would still need significant inference to invoke this tool 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It mentions 'baselReferences' and 'nextOffset', but never explains the top-level parameters (page, offset, pageSize, filters) or their semantics. The large nested filter object is left almost entirely self-describing.

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 ('Read'), a concrete resource ('bounded evidence'), and narrows the scope to 'precomputed editorial, lexical or optional semantic topic assignments.' This distinguishes it from sibling tools like search_works or get_topics_by_period without ambiguity.

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 conveys that this tool reads evidence for topic assignments and supports bibliography filters, so the use case is implied. However, it never explicitly contrasts it with related tools or states when it should be preferred over 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral nuance beyond annotations: default editorial/lexical assignments, the function of includeSemantic, the firstYears author constraint, and the crucial denominator detail that 'percentages use evaluable works, not semantic top-k results.'

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 four sentences with no filler. The core purpose is front-loaded, and each subsequent sentence adds a distinct piece of useful behavior. It is dense but not bloated.

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?

This tool has a complex nested filters schema, seven top-level parameters, zero schema descriptions, and no output schema. The description covers only a few operational specifics (includeSemantic, firstYears, percentage denominator) and omits key context about period definitions, interval semantics, filter behavior, and response structure, making it inadequate for fully correct 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?

With 0% schema description coverage, the description must compensate. It clarifies two important parameters: includeSemantic ('explicitly includes embedding associations') and firstYears ('requires exactly one author and starts at their earliest catalogued work'). However, it leaves periods, interval, pagination, and the interaction between periods and interval undocumented, so gaps remain.

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 pairing: 'Compare precomputed thematic indicators by period.' This clearly identifies the tool's function and distinguishes it from siblings like get_topic_evidence, which focuses on evidence rather than period-based comparison of thematic indicators.

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 no guidance on when to choose this tool over alternatives such as get_topic_evidence or search_works. It provides operational constraints (e.g., 'firstYears requires exactly one author') but does not explain the scenarios that should route an agent to this tool versus its siblings.

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, so the safety profile is established. The description adds that the tool returns Spanish-language invitation content and official contact details, which is useful but modest; it does not describe any edge cases, formatting, or limitations. With strong annotation coverage, a 3 is appropriate.

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, tightly constructed sentence that front-loads the use condition and then states the return contents. There is no redundant wording or repetition of the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, zero-parameter lookup tool with full read-only/idempotent annotations, the description covers what an agent needs: when to call it and what it returns. It even specifies the language (Spanish) and the type of content (invitation and contact details), so no critical information 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?

The tool has zero parameters and an empty input schema, so the description carries no parameter burden. Per the baseline for zero-parameter tools, a 4 is appropriate; the description focuses on invocation context and output rather than inputs.

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 ('returns') and a concrete resource: the Community's Spanish invitation to personal accompaniment and official contact details. It also states the exact triggering conditions (interest in the Community of Saint John, consecration, vocation discernment, or Spiritual Exercises), which clearly differentiates it from sibling tools like get_community_of_saint_john or get_common_life_and_mission.

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 begins with explicit use conditions: 'Use when someone is interested in the Community of Saint John... or asks about vocation, discernment of a state of life, or the Spiritual Exercises.' This gives clear context for when to call the tool, though it does not explicitly name sibling alternatives or state when not to use it.

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 safety profile is covered. The description adds the behavioral detail that it returns 'all its public publications' and that 'Author/type scope applies to IDs too', which is useful. However, it doesn't disclose pagination, size limits, or what 'complete' means in terms of record structure, so it adds only modest context 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?

Two sentences with no filler. The main action and scope are front-loaded, and the additional note about author/type scope is placed at the end. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with strong annotations, the description is mostly adequate. It tells the agent what it returns (work record + public publications) and adds a scoping note. However, with no output schema and no mention of pagination or response shape, an agent may not know what to expect when invoking it. The sibling list includes get_publications and get_publication_text, so a bit more differentiation would improve completeness.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter semantics. The description mentions 'Author/type scope applies to IDs too', which adds meaning to the workId parameter beyond the raw schema pattern. However, it doesn't explain the ID format or how to obtain a workId, so it's not fully complete.

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 ('Get') and resource ('complete bibliographic work record and all its public publications'), which clearly distinguishes it from list_works and search_works. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate from get_publications or get_publication_text, which could overlap in scope.

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 usage: use this when you need a complete work record plus its public publications. It does not explicitly state when not to use it or name alternatives like list_works or search_works. The context is clear enough for an agent to infer, but there is no explicit routing guidance.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to cover safety. It adds useful behavioral details such as returning aliases, article counts, and original years, and it notes that only 'identified' journals are listed (implying some are not). However, it does not describe pagination, filtering behavior, or result ordering, so it leaves several behavioral aspects uncovered.

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 two sentences with no filler. The core action is stated first, and the sibling distinction is added efficiently. It is appropriately concise, though it could have included a brief note about filtering or pagination without being verbose. The structure is front-loaded and effective.

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 complexity of the tool—4 top-level parameters, a nested filters object with dozens of properties, no output schema, and no parameter descriptions—the description is grossly incomplete. It omits any guidance on filtering, pagination, or what the response structure looks like. An agent would struggle to use this tool correctly with only the provided description and schema, as the schema lacks explanatory text for its many properties.

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 description coverage is 0%, meaning the description provides no explanation of any parameters. The input schema has no per-property descriptions, only types and constraints. With 4 top-level parameters including a complex filters object with many nested fields, the description should compensate, but it is completely silent on parameters. This is a severe 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 clearly states the tool's function: 'List identified journals with aliases, distinct article counts and documented original years.' It uses a specific verb (List) and resource (journals), and distinguishes itself from the sibling count_catalog by noting that unknown references are handled there. This makes it clear what the tool does and how it differs from at least one sibling.

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 a hint about when not to use this tool ('Unknown references are reported by count_catalog'), implying that for unknown references one should use count_catalog. However, it does not explicitly mention alternatives like list_publications or list_works, nor does it give clear 'when to use' guidance beyond that single contrast. This is adequate but not comprehensive.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the burden. The description adds valuable behavioral detail about filter semantics—distinguishing workTypes from publicationTypes and noting that filters target the contained work. This goes beyond annotations without contradicting them.

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 two sentences with no filler. It front-loads the core purpose and then explains a key distinction between filter types. However, it could be slightly more structured (e.g., listing parameter groups) but remains efficient.

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 complex schema with 7 top-level parameters and a nested filters object containing 25 properties, the description is incomplete. It does not mention pagination, faceting, sorting, or the output format beyond 'summaries.' No output schema exists, so the description should explain what the returned data looks like. The lack of coverage for common list operations is a significant 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?

With schema description coverage at 0%, the description must compensate for all parameters. It only explicitly names two filter types (workTypes and publicationTypes) and vaguely mentions author/type/original year. It does not explain pagination parameters (page, offset, pageSize), facets, sorting (sortBy, sortOrder), or the many other filter options. This leaves most parameters unexplained.

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: 'List publication summaries.' It is specific about the output being summaries. However, it does not explicitly differentiate this tool from closely named siblings like get_publications or list_works, leaving the agent to infer the difference from the title alone.

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 some usage context by explaining that 'workTypes filters contained works; publicationTypes filters derived publication classification' and that filters match 'the same contained work.' This helps agents understand filter behavior but does not say when to choose this tool over alternatives (e.g., get_publications, search_publication_text) or when not to use it.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive.skipThe description adds meaningful behavioral context beyond annotations: it includes works without digital publications, clarifies that filters are combinable, and specifies that the default year is the original publication year. No contradiction with annotations.

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

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

Three short sentences, front-loaded with the core action, and every sentence adds a useful piece of information. There is no fluff, repetition, or unnecessary detail.

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 high complexity of the schema (nested filters, many optional parameters) and the lack of an output schema, the description is too brief. It does not explain pagination, response shape, or parameter semantics, and an agent would likely need to guess at filter meanings. The description covers high-level purpose but not enough operational 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 0%, so the description must compensate, but it only mentions 'filters', 'facets', and the default year. It does not explain the many nested filter properties, pagination params, or sort semantics beyond one default. The schema is complex with 7 top-level parameters and a large filters object, so this is a significant 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 states a clear verb and resource: 'List public works'. It also signals distinctive features like combinable filters, exact counts, and optional facets, which helps differentiate it from sibling tools. However, it does not explicitly name any sibling or contrast itself with search_works, so it falls just short of full 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?

The description implies a use case: browsing/filtering public works with optional facets and exact counts. It does not explicitly state when to prefer this tool over search_works, count_catalog, or list_publications, nor does it give exclusions. The usage context is present but 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: matching is lexical and accent-insensitive, and results are source evidence rather than generated answers. This goes beyond the annotations and helps the agent set user expectations.

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

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

Two sentences, front-loaded with the core purpose and immediately followed by the key behavioral caveat. Every word earns its place; no fluff or repetition of schema details.

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 search tool with no output schema, the description explains the nature of results (source evidence, not generated answers) and the matching behavior, which is helpful. However, it does not mention pagination, result format, or how the optional parameters (topics, subjects, offset, pageSize) affect the search. Given the tool's moderate complexity and 5 parameters, a bit more context would be needed for full completeness.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. However, the description only explains the 'question' parameter implicitly and the overall search scope; it does not explain 'topics', 'subjects', 'offset', or 'pageSize'. The schema's enums and defaults provide some structure, but the description adds little semantic value beyond the search intent.

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 ('Search'), a precise resource ('exact Spanish passages about Balthasar, Speyr, their common mission and the Community of Saint John'), and clarifies the matching behavior. It distinguishes itself from sibling search tools by specifying the Spanish lexical, accent-insensitive nature and the source-evidence purpose.

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 clearly implies when to use this tool: when the user needs exact Spanish passages as source evidence, not generated answers. It does not explicitly name alternatives or exclusions, but the contrast with 'not generated answers' and the lexical matching detail provide enough context for an agent to select it over other search tools.

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

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

Annotations already flag read-only/idempotent/non-destructive, so the bar is lower, but the description adds meaningful behavioral traits: exact phrase normalization, accent/case insensitivity, bounded context with locators, pagination via nextOffset, and the absence of embeddings/generated summaries. No contradiction with annotations.

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

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

Three tight sentences lead with the core action, add the most important return behavior, and include one clarifying caveat about collective publications. Every sentence earns its place; there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only search tool, the description is nearly complete: it states what is searched, how matching behaves, and what is returned (context, locators, nextOffset). The absence of an output schema makes the return-value description somewhat high-level, but the combination of annotations and schema constraints covers the remaining operational details.

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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It directly clarifies query ('literal phrases... ignoring case and accents') and publicationId ('public publication's extracted EPUB/PDF text'), and it indirectly covers limit/offset through 'bounded exact context' and 'nextOffset.' However, it doesn't explicitly map limit to result count or offset to pagination position.

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: 'Find literal phrases... in a public publication's extracted EPUB/PDF text.' It also disambiguates from siblings like search_works by scoping to full-text phrase search inside a single publication and by explicitly excluding semantic features ('no embeddings or generated summaries').

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 makes the use case clear: literal, case/accent-insensitive phrase search in a specific publication's extracted text. It implies a contrast with semantic search by saying 'no embeddings or generated summaries,' but it does not explicitly name alternative tools or state when to choose get_publication_text or search_works instead.

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?

Goes well beyond the readOnly/openWorld/idempotent annotations by describing multilingual embedding behavior, evidence grouping, language/status/source/coverage identification, and important caveats about catalog descriptions and thematic absence. This gives the agent realistic expectations about result semantics.

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?

Compact and information-dense with no filler. Key facts about multilingual search, result grouping, lexical queries, and limitations are all included in a short description that front-loads the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a large filter schema and no output schema, the description provides useful return-shape details, multilingual semantics, and open-world limitations. It does not explain filters, pagination, or explicit sibling routing, but the annotations and schema fill some of that 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?

Schema description coverage is 0%, so the description carries the burden. It explains query language flexibility and lexicalQueries BM25 terms, but says nothing about the extensive filters object or the limit parameter. This is partial compensation for an otherwise undocumented 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 action: searching public catalog metadata and passages with multilingual embeddings, with results grouped by bibliographic work. This clearly distinguishes it from broader listing tools and from the title alone.

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 clear context that queries may be in any language, explains optional lexicalQueries, and notes that listing tools provide exhaustive bibliographies. It does not explicitly name or contrast the closest sibling, search_publication_text, but gives enough context for many cases.

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