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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It indicates the tool is a read operation ('abrufen') and describes the return type, but it does not address potential side effects, error behavior, or permissions. This provides moderate transparency but leaves notable gaps.

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-organized with clear sections (PURPOSE, WHEN TO USE, Args, Returns) and is reasonably compact. The opening sentence and PURPOSE section are somewhat redundant, and the inclusion of an internal 'ctx' parameter adds noise. Overall, it earns its place but could be tightened.

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 tool with one parameter and an existing output schema, the description covers the essential aspects: what it retrieves, when to use it, the meaning of the argument, and the return type. It does not explain failure modes or empty results, but these are not critical given the tool's simplicity.

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

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

The input schema provides only the parameter name and type, with 0% coverage of description in the schema. The description adds that edition_id is an 'Edition-UUID in correspSearch', which clarifies the expected value. However, it provides no format validation, requiredness context (beyond schema), or further semantics, so it only partially compensates.

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 that the tool retrieves information about an edition in correspSearch and explicitly defines its purpose as returning metadata for registered editions. It uses a specific verb ('abrufen') and resource ('Edition'), making its function clear. However, it does not explicitly distinguish itself from sibling tools, so it falls 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 includes a 'WHEN TO USE' section with three concrete scenarios, offering clear guidance on when to invoke this tool. It does not mention when not to use it or alternative tools, so it misses the explicit exclusion that would merit a 5.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses that it returns an integer or None if not found, which is critical behavioral information. The example also illustrates usage. It does not discuss errors or side effects, but for a simple lookup this is sufficient.

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-organized with clear sections (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Example). Every sentence adds value, and the structure makes information easy to scan.

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 lookup tool, the description provides all needed context: purpose, usage guidance, return behavior, parameter semantics, and a concrete example. An output schema exists but the description clarifies what is returned, making it 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 provides no parameter descriptions (0% coverage), but the description includes an Args section explaining 'place_name' with examples and 'country' as an optional ISO-2 code restricting search. This fully compensates for the schema 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?

Description clearly states it gets a GeoNames ID for a place, distinguishing it as a quick lookup from cs_search_for_geonames_id which handles ambiguity. The verb 'Get' and resource 'GeoNames ID' are specific, and the convenience function framing sets expectations.

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

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

Explicit WHEN TO USE and WHEN NOT TO USE sections provide clear guidance. It names the alternative tool for ambiguous names, making the decision process straightforward.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals several important behaviors: it uses an external correspSearch API, multiple person IDs are combined with AND logic (in the Note), text_query is marked as experimental and undocumented, and pagination details (page is 1-indexed, 100 per page) are specified. It does not explicitly state the operation is read-only, but the search-oriented purpose strongly implies it, and the description otherwise provides substantial behavioral context.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Note) and front-loaded with purpose and usage guidance. It is somewhat long due to 15 parameters, but each section earns its place and the length is justified by the tool's complexity. A minor issue is the inclusion of 'ctx' as an argument that is not present in the input schema, but this is likely a framework context and does not significantly detract from clarity.

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 (15 parameters, no annotations) and the presence of an output schema, the description provides comprehensive context: explicit purpose, when to use/not use, detailed parameter semantics, return type (CorrespSearchResult with pagination info), and an important behavioral note about AND combination. There are no significant gaps, as it covers all critical aspects an agent would need to correctly select and invoke the tool.

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 0% description coverage, so the description must compensate, and it does excellently. Each parameter in the Args section is explained with types, example values, and allowed options (e.g., person_gnd can be a single string or list of IDs, availability options 'online', 'print', 'hybrid', page is 1-indexed with 100 results per page). This adds far more meaning than the bare schema, with concrete examples for nearly every 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 opens with 'Cross-Edition Briefsuche über correspSearch API' and explicitly states PURPOSE: 'Briefe über Edition-Grenzen hinweg finden' (find letters across editions). This clearly identifies a specific verb (search/find) and resource (letters) with a unique scope that distinguishes it from sibling tools like sd_search_letters, which is Schleiermacher-specific.

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 dedicated WHEN TO USE section listing concrete scenarios (e.g., user wants letters in ALL editions, cross-referencing between editions, comprehensive correspondence network analysis). It also has a WHEN NOT TO USE section explicitly stating that for Schleiermacher-specific search one should use sd_search_letters(), giving a clear alternative and exclusion.

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?

No annotations are provided, so the description must carry the full burden. It does provide behavioral details like 'max_letters_to_analyze ... (pro Richtung)', but it does not explicitly state whether the tool is read-only, what side effects exist, or any access requirements. This is adequate but not rich.

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-organized into PURPOSE, WHEN TO USE, Args, and Returns sections. It is front-loaded with the core purpose and uses bullet-like formatting for parameters. Each section earns its place without unnecessary fluff.

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 the tool's complexity (network analysis, 5 parameters, no annotations), the description covers purpose, usage, parameters, and return value. An output schema exists, so return details are not repeated. Minor gaps like date format are not specified, but overall it is largely 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?

With 0% schema description coverage, the description compensates well by listing each parameter with a meaningful explanation (e.g., 'person_gnd: GND-ID der fokalen Person', 'start_date: Optional: Start-Datum für Zeitfilter'). It also adds the nuance 'pro Richtung' for max_letters_to_analyze, going beyond the schema.

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

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

The description opens with 'Korrespondenz-Netzwerk einer Person analysieren', clearly specifying the verb (analysieren) and resource (correspondence network of a person). The PURPOSE section reinforces this and distinguishes it from sibling search tools like cs_search_correspondences by focusing on network analysis.

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 WHEN TO USE section provides concrete usage scenarios (e.g., 'Mit wem korrespondierte Person X?', preparing network visualizations, identifying key partners). This gives clear context, though it does not explicitly state when not to use the tool or name alternative 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?

No annotations are provided, so the description carries the full burden. It discloses the return format (list of dicts with specific fields), demonstrates usage via an example, and clarifies input constraints. However, it does not mention edge cases like empty results or potential ambiguity, but for a search tool this is adequate 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 well-organized with clear headings (PURPOSE, WHEN TO USE, Args, Returns, Example), front-loaded with purpose, and every section adds value. It is appropriately sized given the need to compensate for missing schema descriptions and annotations.

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

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

The description covers purpose, usage conditions, parameters, return format, and a concrete example. Given the output schema exists and the tool is a relatively simple search, this is complete. It also distinguishes from related tools effectively, making it comprehensive for an agent.

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?

Input schema has 0% description coverage, but the description's 'Args' section explains each parameter (place_query, country, limit) with clear semantics and examples. This fully compensates for the schema's lack of detail, and the example illustrates proper 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?

The description begins with 'Search for GeoNames IDs by place name', clearly identifying the specific resource and action. It distinguishes from sibling tools by specifying correspSearch filtering and directing users to search_for_gnd_id() for person/organization names.

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 'WHEN TO USE' and 'WHEN NOT TO USE' sections explicitly state the scenarios for using this tool, including alternatives for different entity types and when an ID is already available. This clearly differentiates from sibling tools like cs_search_for_gnd_id.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently states the use of the Lobid GND API, describes the return format as a list of dicts with 'id' and 'label', and includes an example showing how to extract the GND ID from the URI. It does not mention error handling or rate limits, but for a simple search tool the key behaviors are adequately disclosed.

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 section headings (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Example). Each section is concise and purposeful, and the example adds practical value without redundancy, making it easy for an agent to parse.

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 lack of annotations and minimal schema, the description is remarkably complete. It covers purpose, usage, parameters, return values, and includes a detailed usage example with async syntax, showing the output and subsequent use. This provides all necessary context for an agent to 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?

Schema description coverage is 0%, and the description fully compensates by documenting both parameters in the Args section: name_query is described as 'Name or term to search for' with examples like 'Goethe', and limit is defined as 'Maximum number of results to return'. This adds meaningful semantics far beyond the bare schema types.

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 'Search for GND IDs by name using Lobid GND API' and further defines the PURPOSE as finding GND identifiers for persons, places, or corporate bodies. This distinguishes it from sibling tools like cs_search_for_geonames_id and cs_search_wikidata_entity, which target different ID systems.

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 includes explicit WHEN TO USE sections, stating to use this tool when needing a GND ID for correspSearch filtering, resolving person names, or enriching metadata with authority data. It also provides WHEN NOT TO USE guidance, directing users to get_gnd_entity() for full entity data and other services for non-GND authority data, thereby clarifying 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?

No annotations are provided, so the description carries the full burden. It discloses the return format (list of dicts with id, label, description, uri) and provides a usage example. It does not explicitly mention side effects or rate limits, but 'search' implies a read-only operation. Minor gap: no explicit statement that it does not modify data or require authentication, but the example and return details give good 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 well-organized with clear sections (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Example). It is front-loaded and every section adds value. The example is concise and informative. No redundant or vague wording.

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

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

The tool is simple (a search with two parameters) and the description covers purpose, usage, parameters, return format, and an example. Although an output schema exists, the description independently documents the return structure, which is valuable given the output schema was not provided in the prompt. It also differentiates from the large sibling tool set.

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 fully explain parameters. It does: occupation_query is described as an occupation name with examples (e.g., 'Dichter', 'Philosoph', 'Maler'), and limit is described as the maximum number of results. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool searches for occupation entities in Wikidata, with the specific purpose of finding Wikidata IDs for filtering correspondence by profession. It distinguishes itself from sibling tools by explicitly naming alternatives for person names, places, and non-occupation entities.

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 'WHEN TO USE' section lists concrete use cases (e.g., finding occupation IDs for correspSearch filtering, professional network analysis), and the 'WHEN NOT TO USE' section explicitly names sibling tools with clear exclusions. This provides strong guidance on tool 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?

No annotations are provided, so the description carries the full burden. It discloses the return format ('List of dicts with entity information'), includes an example call, and notes the default language. While it doesn't explicitly state read-only behavior or rate limits, the search context implies a safe operation and the return structure adds value beyond 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 well-structured with headings, bullet lists, and an example. It is slightly longer than strictly necessary but each section earns its place. The purpose phrase is repeated ('Search for any entity' and 'General-purpose entity search'), which is minor 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 search tool, the description covers everything needed: purpose, when to use and when not, parameters, return format, and a concrete example. It also differentiates from sibling tools (occupation/GND/GeoNames searches), ensuring the agent has full context.

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

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

Schema description coverage is 0%, but the description compensates by explaining each parameter in the 'Args' section: query as the search term, limit as max results, and language as a code with default 'de'. It also clarifies the return structure, giving full semantic meaning.

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 'Search for any entity in Wikidata', using a specific verb and resource. The PURPOSE section further clarifies it as a general-purpose entity search, and the WHEN NOT TO USE section explicitly distinguishes it from occupation-specific search (cs_search_for_wikidata_occupation).

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

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

Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections provide clear conditions and name alternative tools (e.g., 'search_for_wikidata_occupation()' for occupations), making it easy for an agent to choose correctly.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does describe the return shape ('files' and 'subcollections'), the use of ctx for progress, and its exploratory nature. However, it does not explicitly state that the operation is read-only, nor does it mention error behavior or permission requirements, leaving some ambiguity.

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

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

The description is well-structured with clear sections and a strong first sentence. There is minor redundancy between the English opening and the German PURPOSE line, and the Args section includes a non-schema ctx parameter, but overall it is scannable and efficiently written.

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 browse tool with an output schema, the description covers purpose, usage boundaries, argument semantics, and return structure. It is nearly complete, but the undocumented ctx parameter and lack of explicit read-only/error details keep it from being fully self-sufficient.

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%, but the description compensates by explaining collection with example values (Texte, Register) and limit as 'Maximale Anzahl Dateien,' adding meaning beyond the bare schema. On the downside, it also documents a ctx parameter that is not present in the input schema, which could potentially confuse an agent about what arguments to supply.

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 first sentence clearly states the tool's function with a specific verb and resource: 'Browse files and subcollections in MoP.' The PURPOSE section reinforces that it provides an overview of available files, and the WHEN NOT TO USE section distinguishes it from search_documents and get_document, making it easy to tell apart from siblings.

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

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

The description provides explicit WHEN TO USE and WHEN NOT TO USE sections. It tells the agent to use this for exploration without a concrete search term, and to use search_documents() instead for specific searches and get_document() for metadata. This is strong alternative 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?

No annotations are provided, so the description carries the full burden. It discloses the return type (DatabaseStatus with connection status, version, paths) and implies a non-destructive health check. Yet it omits details like timeout behavior or whether any configuration is required, which would strengthen 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 well-structured with headings (PURPOSE, WHEN TO USE, Returns) and is highly concise. Every line adds value, front-loading the main purpose before supporting 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 simple zero-parameter tool with an output schema, the description is largely complete, covering purpose, usage, and return values. A minor gap is the lack of clarification about which database is checked (mop vs. sd), which could be relevant given the sibling sd_check_database_connection.

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, so the baseline is 4. The description naturally adds no parameter-specific information, as there are none to document. The schema with empty properties confirms this, making the description complete on this dimension.

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 checks database reachability and responsiveness, with an explicit PURPOSE line. However, it does not distinguish between this tool and the similarly named sibling sd_check_database_connection, relying on the name prefix to imply a different database.

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?

A dedicated WHEN TO USE section provides clear scenarios: troubleshooting failed tools, verifying setup, and health monitoring. It does not mention when not to use it or direct to alternatives, but the context is sufficiently 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?

With no annotations provided, the description takes on the full burden. It clearly states the tool is read-only ('Don't use for write operations (read-only!)') and describes the return format ('Raw query result as string (usually XML)'). It adds useful context about being for advanced users/debugging, though it omits potential error behavior or performance considerations.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns) and is front-loaded with the core purpose. It is slightly longer than strictly necessary but every section contributes value, with 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?

The description is fairly comprehensive for a debugging tool: covers purpose, usage guidance, read-only constraint, parameters, and return value. Given that an output schema exists, the Returns section is optional but harmless. The main gap is not explaining how this tool differs from the sibling 'sd_execute_xquery', which would complete the context.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining 'query' as an XQuery string and 'max_results' as the maximum number of results to return. This adds meaningful semantics beyond the bare schema types, though it does not elaborate on defaults or edge cases.

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 ('Execute') and resource ('raw XQuery against the database'), and adds context about advanced users/debugging. However, it does not differentiate between this and the similarly named sibling 'sd_execute_xquery', so it lacks explicit sibling distinction.

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 explicit when-to-use and when-not-to-use sections, including the important exclusion of write operations and direction to use specific tools for common operations. However, it does not name any specific alternative tools, instead referring to 'specific tools' generically.

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?

No annotations are present, so the description carries the full burden. It discloses that the tool analyzes kinship relationships and returns a dict of family relations structured by type, and 'extrahieren' implies a read-only operation. It does not cover edge cases like missing biograms or empty networks, but for a single-ID extraction this is reasonable.

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 PURPOSE, WHEN TO USE, Args, and Returns sections, and the opening line is immediately informative. The three use-case bullets are somewhat redundant but do not waste more than a line, keeping the overall description 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 single-parameter contract and the presence of an output schema, the description is sufficiently scoped: it states input, purpose, and general return shape. It does not discuss error handling or the exact taxonomy of family relation types, but those details are likely covered by the output schema.

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

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

Schema coverage is 0%, but the description compensates fully by clarifying that biogramm_id is the 'XML-ID des Biogramms' and that ctx is the FastMCP Context. This adds essential meaning beyond the bare string schema for the only required 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 opens with a specific verb+resource: 'Familiennetzwerk aus einem Biogramm extrahieren' (extract family network from a biogram). This clearly distinguishes it from siblings like mop_get_biogramm_by_id or mop_search_biogramme by emphasizing relationship extraction rather than fetching or searching the biogram itself.

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?

A dedicated 'WHEN TO USE' section explicitly lists genealogical research, reconstructing court networks, and analyzing family dynasties at court. This gives clear context for when to invoke the tool, but it does not mention when not to use it or name alternatives, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the return structure, the possibility of ToolError for not found or retrieval failure, and the ctx parameter for progress reporting. It does not discuss access control or side effects, but for a read-only retrieval tool this is quite transparent. A slight gap is the lack of detail on text format, but overall it is strong.

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?

Though lengthy, the description is well-organized with clear headers (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Raises). Every section contributes essential information, and the primary description is front-loaded. No redundant content exists.

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

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

This tool has a complex return type (days list with multiple nested fields) and no formal output schema, but the description includes a full return dict structure. It also covers error handling, parameter sourcing, and usage context, making it complete for an agent to invoke correctly without any additional documentation.

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

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

Schema coverage is 0%, but the description fully compensates by defining document_id as 'Document ID from search results (e.g., 'P0005285')'. This tells the agent where to get the value and provides an example format. For a single required parameter, this is excellent semantic enrichment.

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: 'Retrieve full text and metadata of a specific journal entry.' It clearly differentiates from sibling tools by stating it is used after search_adjutanten_journals() and contrasts with get_register_entry(). The purpose is unambiguous and distinct.

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

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

Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections are provided. It specifies using this tool after search_adjutanten_journals() and lists alternatives for searching multiple entries (search_adjutanten_journals()) and biographical data (get_register_entry()). This gives clear decision criteria for an agent.

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?

No annotations are provided, so the description carries the burden. It does not explicitly state read-only behavior or error handling, but the retrieval semantics are clear from 'abrufen'. It lacks disclosure of any potential side effects, permissions, or rate limits, though these are less critical for a get-by-ID operation.

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, WHEN TO USE, Args, Returns). Every sentence earns its place, with no redundant information. It is concise yet informative, making it easy for an agent to parse.

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

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

Given the tool's simplicity (one parameter, output schema present), the description covers purpose, usage, parameters, and return type. It lacks error-case behavior, but that is not required given the output schema's presence. The description is adequately complete for an agent to 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 description for biogramm_id (0% coverage), but the description compensates by defining it as an XML-ID and providing an example ('P0005251'). This adds meaningful semantics beyond the bare schema, though it doesn't explain how to discover the ID (e.g., from search results).

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

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

The description clearly states the tool retrieves a complete biography with all details, using the specific verb 'abrufen' and resource 'Biogramm'. It distinguishes itself from sibling tools like mop_search_biogramme by focusing on fetching by ID rather than searching, aligning with the tool name.

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?

There is an explicit 'WHEN TO USE' section that tells the agent to use this tool after search_biogramme() to get details, and for analyzing family networks, careers, or possessions. It also names the alternative tool, providing clear context and 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?

No annotations are provided, so the description carries the full burden. It does state what it returns ('Document-Objekt mit Metadaten und Content') and the include_xml option, which adds value. However, it does not explicitly disclose that this is a read-only operation with no side effects, nor does it mention error behavior or permissions for a getter that is likely read-only. The description is adequate but not rich on behavioral context.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns). Every sentence adds value and it is front-loaded with the main purpose. No fluff or repetition beyond the minor overlap between the title and PURPOSE, which is acceptable.

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

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

For a simple two-parameter getter tool with an output schema, the description is complete. It covers purpose, usage guidelines, parameter semantics, and return shape. The presence of an output schema means return values need not be further explained. The inclusion of alternatives in the WHEN NOT TO USE section rounds out the guidance.

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

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

Schema coverage is 0%, so parameters would be unclear without description. The description explains both parameters well: 'Die xml:id des Dokuments' for document_id and 'Ob TEI-XML inkludiert werden soll' for include_xml. However, it lists 'ctx: FastMCP Context' as an argument that is not in the schema, which could confuse the agent if it attempts to pass it explicitly.

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 'Vollständiges Dokument abrufen' (retrieve complete document) and states PURPOSE as 'Detaillierte Ansicht eines spezifischen Dokuments' (detailed view of a specific document). It clearly names the verb and resource, and differentiates from browse/search tools in the WHEN NOT TO USE section.

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

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

Explicit WHEN TO USE ('User möchte ein Aktenstück lesen', 'Nach erfolgreicher Suche → Details anzeigen') and WHEN NOT TO USE ('Für Übersicht → nutze browse_documents() oder search_documents()') with named alternatives. This is exactly the kind of guidance needed.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It mentions a return dict but does not state whether the operation is read-only, how errors are handled, or any prerequisites. The inclusion of a 'ctx' argument not present in the schema adds confusion about expected inputs.

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 PURPOSE, WHEN TO USE, Args, and Returns sections, and is reasonably compact. Minor redundancy between the title line and PURPOSE, plus the extra ctx parameter, add slight noise.

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

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

Given the tool's simplicity, the description covers essential purpose, usage context, and return type. However, it does not explain how to obtain entry_id or valid register_type values, and the ctx parameter creates schema inconsistency. The presence of an output schema partially offsets the return detail 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 schema has 0% parameter descriptions, so the description must compensate. It offers only trivial glosses like 'ID des Registereintrags' and 'Register-Typ' that largely repeat parameter names, and lists 'ctx' which is absent from the schema. This does not clarify how to source entry_id or what register_type values are valid.

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 'Detailansicht eines Registereintrags' and 'Vollständige Informationen zu Person, Ort, etc.', identifying the tool as a detail retriever for register entries. This distinguishes it from search tools like mop_search_register and other getters like mop_get_biogramm_by_id.

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 'WHEN TO USE' section explicitly says to use after a register search and for biographical/geographical details, providing clear context. It does not name alternatives or exclusion criteria, which prevents a perfect score.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the return structure (year, total_features, features_with_coordinates, categories, cities, sample_features, query_methods), error behavior (Raises ToolError for invalid year or API failure), and accepted year values. This is rich behavioral context beyond minimal safety declarations.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Raises) that front-load the core purpose. Each section earns its place by providing necessary operational or decision-making information, with no redundant filler.

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

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

Given the tool's simple interface (1 parameter) and lack of annotations, the description covers all essential aspects: purpose, usage scenarios, parameter constraints, return structure, and error conditions. It is fully self-sufficient for correct selection and invocation, making it contextually 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 input schema provides only a bare integer 'year' with no description (0% coverage). The description compensates fully by specifying the valid years (1800, 1845, 1872, 1891, 1914) and explaining the context parameter (ctx) for progress reporting. It adds crucial meaning that the schema lacks.

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 statement ('Fetch complete residential topography dataset for a specific year') and elaborates in PURPOSE that it retrieves GeoJSON data about residences in Berlin and Prussia. This clearly distinguishes the tool's focused scope from siblings like mop_search_residential_topography.

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 contains explicit WHEN TO USE and WHEN NOT TO USE sections, listing concrete scenarios (e.g., 'User asks about where people lived in a specific year') and providing named alternatives for exclusions ('use search_register() for biographical register data', 'use browse_documents() or search_documents() for document texts'). This meets the highest standard for usage 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?

No annotations are provided, so the description carries the full burden. It discloses error behavior ('Raises: ToolError if monarch is invalid or query fails') and the internal notion of analyzing journal entries ('total_entries: Number of journal entries analyzed'). However, it does not explicitly state that the operation is read-only or describe any side effects, though the 'List' verb and return structure imply a safe read operation.

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 longer than typical but well-structured with clear headers (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Raises). The PURPOSE section somewhat repeats the first sentence, but every other section earns its place by adding necessary selection guidance, parameter details, and error semantics. The use of consistent formatting aids readability.

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 modest complexity (one parameter, no annotations, no schema descriptions), the description is exceptionally complete. It documents valid parameter values, expected return fields (monarch, total_entries, adjutants list with subfields), error conditions, and explicitly differentiates from sibling tools. The output schema's existence does not undercut the value added by the description's explanatory 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?

The input schema only defines 'monarch' as a string with 0% description coverage. The description compensates fully by enumerating all valid values: 'Friedrich_Wilhelm_IV, Wilhelm_I, Wilhelm_II, Friedrich_III' and warning that invalid monarchs will raise a ToolError. This transforms an otherwise opaque string parameter into a self-documented, constrained input.

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+scope: 'List all adjutants who served under a specific monarch.' It clearly distinguishes itself from siblings by explicitly directing users to 'search_register()' for biographical data and to 'search_adjutanten_journals()' for journal content, preventing confusion with similar 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 provides a dedicated 'WHEN TO USE' section with concrete example user queries (e.g., 'Who served as adjutant under Wilhelm I?') and a 'WHEN NOT TO USE' section that names specific alternative tools. This is explicit guidance for tool selection, far beyond the minimum required.

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?

No annotations exist, so the description must carry the behavioral disclosure burden. It does state the return type: 'Dict with available years and description.' However, it does not disclose potential behaviors such as empty results, ordering, or access prerequisites. For a simple list operation, this is adequate but not particularly informative.

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, WHEN TO USE, Returns) and is mostly succinct. There is minor redundancy between the opening sentence and the PURPOSE statement, but overall every section earns its place without excessive prose.

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 that the tool has no parameters and an output schema is present, the description covers all necessary aspects: purpose, usage scenarios, and return type. It is a complete description for a simple list operation, with no critical information 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, so the schema comprehensively covers all parameter aspects. The description accordingly omits parameter details, which is appropriate. Per the rubric, a 0-parameter tool receives a baseline of 4, and there is nothing to add beyond the schema.

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

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

The description clearly states the tool's action: 'List all available years for residential topography data.' The PURPOSE section reinforces this by saying 'Show which years have Wohntopographie datasets available.' It also distinguishes itself from siblings like mop_get_residential_topography and mop_search_residential_topography, which handle specific data retrieval rather than year enumeration.

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

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

The 'WHEN TO USE' section explicitly lists three relevant scenarios: when the user asks about time periods, wants to know queryable years, or before choosing a year for analysis. This gives clear usage context, but it does not explicitly mention non-use cases or alternative tools, so it falls just short of a 5.

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

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

With no annotations provided, the description carries the full burden and does well: it specifies the return format with fields like id, monarch, date range, place, authors, snippet, and url, and even notes that ToolError is raised for invalid monarch or query failure. This goes beyond a basic search description, making the behavior predictable.

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 bold headers and front-loaded purpose, but it is relatively long due to the detailed Args and Returns sections. While every sentence adds value, the length could be trimmed slightly without losing clarity, making it less concise than ideal.

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 that there are no annotations and no output schema, this description is exceptionally complete. It covers purpose, usage conditions, parameter semantics, return fields, error behavior, and even alternatives to non-journal searches, making it fully actionable for an agent.

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?

All 7 parameters are explicitly described with types, formats, and examples: query is the full-text search term, monarch lists valid values, date_from/date_to require ISO format, person_key/place_key use register keys like 'P0002157', and limit defaults to 50. This fully compensates for the 0% schema 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 opens with 'Search in Adjutantenjournale (court adjutant journals)' and clearly states 'Find daily court journal entries documenting royal activities, audiences, meetings, and events.' This specific verb+resource phrasing distinguishes it from sibling tools like mop_get_adjutanten_journal_entry, which focuses on retrieving a single entry.

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 'WHEN TO USE' section lists concrete user queries (e.g., 'What did the king do on [date]?'), while 'WHEN NOT TO USE' provides explicit alternatives: search_register for biographical data, letters search in Schleiermacher Digital for correspondence, and browse_documents for institutional documents. This directly guides tool 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?

No annotations are provided, so the description carries the full burden. It discloses the search behavior, intended use cases, and the return structure ('Liste von Biogramm-Treffern mit id, name, birth, death, gnd'). It does not explicitly state read-only semantics, but 'Suche' strongly implies it, and there are 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, WHEN TO USE, WHEN NOT TO USE, Args, Returns). It is slightly verbose with minor redundancy between the opening sentence and the PURPOSE section, but overall every section earns its place and it remains easy to scan.

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 4 simple parameters and an output schema (indicated), the description provides a return format and usage context. It lacks examples, error conditions, or pagination details, but for this level of complexity it is 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?

The input schema has 0% description coverage, but the description's 'Args' section explains every parameter: 'query: Suchbegriff (Name)', 'birth_year: Filter nach Geburtsjahr', etc. This adds meaning beyond the bare schema. The inclusion of 'ctx: FastMCP Context' is slightly problematic because ctx is not in the visible schema, but the core parameters are well described.

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: 'Suche in MoP-Biogrammen (detaillierte Biografien)' and a PURPOSE section stating 'Detaillierte biografische Einträge finden.' This clearly distinguishes from sibling tools like mop_search_register and mop_search_documents by specifying that it targets detailed biographical entries.

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 explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, including concrete alternative tools ('nutze search_register("personen")', 'nutze search_documents()'). This is exactly the kind of usage guidance that helps an agent decide when to invoke this tool over 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?

No annotations are provided, so the description must disclose behavior. It describes the tool as a full-text search and returns a list of SearchResult objects, implying a read-only operation, but it does not mention any specific permissions, side effects, or limitations. For a simple search tool, this is adequate but lacks deeper behavioral context.

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 PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, and Returns sections, each concise. The inclusion of 'ctx: FastMCP Context' is unnecessary and slightly noisy, but overall 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 simple search tool with an output schema and 3 parameters, the description covers purpose, usage context, exclusions, and parameters. It does not detail collection options or result behavior, but it is adequate for the tool's complexity.

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 Args with short German explanations (keyword: Suchbegriff, collection: Collection, max_results: Maximale Ergebnisse). However, these largely mirror the parameter names and add little semantic depth; 'ctx' is mentioned but not in the schema.

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

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

The description clearly states 'Volltextsuche in MoP-Dokumenten' (full-text search in MoP documents) and defines PURPOSE as finding documents containing a specific term. It distinguishes itself from register search by explicitly stating WHEN NOT to use it for structured register search, directing to 'search_register()'.

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 includes explicit 'WHEN TO USE' (search for person, institution, topic; exploratory search on court practices) and 'WHEN NOT TO USE' (structured register search), naming an alternative tool. This provides clear selection 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?

Es sind keine Annotationen vorhanden, daher muss die Beschreibung Verhalten offenlegen. Sie nennt das Rückgabeformat (Liste mit id, name, type, gnd), aber keine weiteren Verhaltensaspekte wie Paginierung, Sortierung oder Nebenwirkungen. Für ein Suchtool ist dies minimal akzeptabel, aber nicht reichhaltig.

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?

Die Struktur mit PURPOSE, WHEN TO USE, Args und Returns ist klar und gut lesbar. Die erste Zeile 'Suche in MoP-Registern' wiederholt teilweise die PURPOSE, aber das ist vertretbar und kein überflüssiger Ballast.

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?

Das Tool hat 3 Parameter, ein Output-Schema ist laut Kontext vorhanden, und die Beschreibung liefert Zweck, Nutzungszeitpunkt, Alternativen und Rückgabefelder. Die fehlende Abgrenzung zum ähnlichen Tool 'sd_search_register' ist eine Lücke, aber insgesamt ist die Beschreibung für die Nutzung ausreichend vollständig.

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?

Die Schema-Abdeckung ist 0%, aber die Beschreibung erklärt query, register_type inklusive erlaubter Werte (personen, orte, institutionen, hoefe, werke, aemter) und max_results. Zusätzlich wird 'ctx' genannt, das nicht im Schema auftaucht – das ist etwas irreführend, aber insgesamt kompensiert die Beschreibung das Schema gut.

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?

Die Beschreibung nennt konkret 'Suche in MoP-Registern' und PURPOSE: 'Strukturierte Registereinträge finden', was Verb und Ressource klar macht. Sie grenzt sich aber nicht von dem Schwester-Tool 'sd_search_register' ab, daher kein voller Punkt.

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?

Es gibt explizite 'WHEN TO USE'- und 'WHEN NOT TO USE'-Sektionen. Die Anwendungsfälle (Person, Ort, Institution, Hof) und die Alternative für Volltextsuche ('search_documents()') werden klar benannt.

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?

No annotations are present, so the description carries the full burden. It discloses critical behavioral traits: filtering semantics (partial match, case-insensitive), valid year values, raising ToolError for unavailable years or missing filters, and returning a structured dict with counts and results. This goes beyond a basic search tool description.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Raises). While it is somewhat long, the length is justified by the 10 parameters and the need to compensate for unschema-documented properties. It could be slightly trimmed, but no content is wasted.

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 10 parameters, no annotations, and no schema descriptions, this description is remarkably complete. It covers purpose, usage contexts, parameter semantics, return structure, and error conditions. The output schema exists, but the description adds necessary filter behavior and validation details, making it self-sufficient for an agent.

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%, but the description documents every parameter with meaningful detail: year lists valid values, name/vorname specify partial match and case-insensitivity, only_with_coordinates explains its filtering effect, and max_results is described in the return section. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states 'Search residential topography data with multiple filters' and further defines the purpose as 'Find persons/institutions by various criteria in historical address data.' It also distinguishes itself from siblings by explicitly naming get_register_entry and get_residential_topography as alternatives in the WHEN NOT TO USE section.

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 dedicated WHEN TO USE and WHEN NOT TO USE sections, listing concrete scenarios (e.g., searching by person, address, profession) and explicitly naming alternative tools for other needs. This is exemplary usage 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?

No annotations are provided, so the description carries the full burden. It describes the check action and return shape (DatabaseStatus object), but does not explicitly state whether the operation is read-only or what happens on failure. It implies a safe health check but lacks explicit disclosure of side effects.

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 uses clear section headers for PURPOSE, WHEN TO USE, and Returns. There is minor redundancy between the opening line and the PURPOSE statement, but overall it is well-structured and 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 simple 0-parameter health check, the description covers the purpose, usage scenarios, and return value sufficiently. It could further clarify which database it checks and any permission requirements, but these are minor gaps given the output schema and simplicity.

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 the input schema confirms this. The description correctly adds no parameter information, matching the baseline for 0-parameter tools.

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 explicitly states 'Check if the database is reachable and responsive' and includes a PURPOSE line that clarifies connectivity verification. However, it does not explicitly differentiate from the sibling tool mop_check_database_connection, relying on the name prefix for context.

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 'WHEN TO USE' section provides concrete scenarios: when other tools fail unexpectedly, to verify setup, and for health monitoring. This gives clear context, though it does not mention when not to use the tool or name alternative 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?

With no annotations provided, the description carries full burden. It explicitly states the tool is read-only, which is a critical behavioral trait. It also mentions it returns raw results as a string, providing transparency about output format. It does not discuss risks or performance implications, but the read-only note is significant.

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 headings and bullet points. Every section provides necessary information, and the first sentence is a clear summary. The length is appropriate for the tool's complexity, and no content is wasted.

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 purpose, usage guidelines, parameters, and return format. Given the output schema, it doesn't need to detail return values beyond the raw string mention. It is complete enough for a raw query tool, though it could mention error handling or permission requirements.

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's Args section is essential. It defines query as an 'XQuery string to execute' and max_results as 'Maximum number of results to return'. These explanations add basic meaning beyond the schema, but lack details like default values or constraints.

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

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

The description uses the specific verb 'Execute' and clearly identifies the resource as 'raw XQuery against the database', making the tool's function obvious. It also states its intended audience (advanced users/debugging), which helps distinguish it from common operations. However, it does not explicitly differentiate from the similarly named sibling mop_execute_xquery.

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 includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, providing clear guidance on usage conditions (advanced/debugging) and exclusions (common operations, write operations). It does not name specific alternative tools, only referring to 'specific tools', which is slightly less actionable.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It notes the tool is 'FAST - uses cache' and states the return type (List of Letter objects). However, it does not explicitly state that the operation is read-only and non-mutating, though 'filter' strongly implies it does not modify data. This is a minor gap.

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 sections (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns). Every sentence adds value, and the format is scannable. It is appropriately sized for a tool with six parameters and clear exclusions.

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 having no annotations and low schema coverage, the description provides complete information: purpose, usage examples, exclusions, parameter semantics, and return type. The output schema exists and covers return structure, so the description need not explain Letter objects further. It is complete for correct 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?

Schema description coverage is 0%, so the description must compensate. It does so effectively by explaining each parameter with types and examples (e.g., sender: 'Person ID of sender (from register, e.g., S0003676)', send_place: 'Place ID or name of sending location'). This adds substantial meaning beyond the raw schema.

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

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

The description clearly states 'Filter letters by sender, receiver, place, and time period' – a specific verb and resource, and it distinguishes from siblings by referencing alternative tools for keyword and register searches. The purpose is immediately understandable and unambiguous.

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 includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete example queries and names of alternative tools (e.g., search_by_keyword, search_register). This provides excellent guidance for an agent to select this tool over 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?

No annotations are provided, so the description carries the full burden. It discloses important behavior: results are returned chronologically, include specific dates and date ranges that overlap with the query, and are structured as a list of dictionaries. It does not explicitly state side-effects or read-only nature, but as a 'get' tool, this is reasonably implied. Adding boundary behavior (e.g., inclusive/exclusive dates) would push this to 5.

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

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

The description uses clear sections (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns) with no wasted sentences. The purpose line is slightly redundant with the first sentence, but the actionable 'WHEN' bullet points and compact parameter descriptions make it exceptionally well-structured and 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 simple two-parameter tool with an output schema, the description provides everything needed: purpose, use cases, exclusions, parameter formats, and return format. It is fully self-contained and does not require the agent to infer behavior from annotations or schemas.

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%, but the 'Args' section fully documents both parameters, including ISO 8601 format and start/end meaning. It also mentions ctx (FastMCP Context), which adds context beyond the schema. This completely compensates for the lack of schema descriptions.

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

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

The description clearly states 'Retrieve chronology entries for a date range' with a specific verb, resource, and scope. It explicitly distinguishes from siblings in the 'WHEN NOT TO USE' section by directing users to get_chronology_entry, get_chronology_year, and search_documents.

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 explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete use cases (biographical timeline, temporal analysis) and specific alternative tools. This goes beyond vague guidance and fully covers when to use this tool versus 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?

No annotations are provided, so the description carries the burden. It discloses the return type (list of dictionaries), notes multiple events may occur, and the verb 'retrieve' implies a read-only operation. However, it does not explicitly state safety guarantees or error behavior, which would be useful but is not critical for a simple getter.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns) and front-loaded with the core action. While there is slight redundancy between the first sentence and PURPOSE, every section adds valuable information, making it appropriately concise for its richness.

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

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

Given the tool's simplicity (one parameter), the description fully covers the purpose, usage, parameter format, and return type. The output schema exists, so no further return-value detail is needed. The description is complete for an agent to 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 input schema provides no description for the 'date' parameter (0% coverage), but the description fully compensates by explaining the required ISO 8601 format with a concrete example. It also mentions the 'ctx' context parameter, making parameter usage clear.

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 'Retrieve chronology entries for a specific date,' which clearly states the verb, resource, and scope. It distinguishes itself from sibling tools like sd_get_chronology_entries and sd_get_chronology_year by emphasizing 'specific date' versus ranges or years.

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 includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, naming exact alternative tools for date ranges, entire years, and keyword searches. This provides clear selection guidance beyond the schema and annotations.

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?

With no annotations, the description carries the burden of behavioral disclosure. It indicates a read-only retrieval operation, describes the return structure (dictionary with year, heading, list of entries), and notes that entries are sorted chronologically. However, it does not mention error behavior, pagination, or any access limitations.

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, but it contains some redundancy (the first sentence duplicates the PURPOSE section) and includes a reference to 'ctx' that adds noise. Overall, it is efficient but not perfectly 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 single-parameter tool with an output schema, the description provides sufficient context for selection and invocation, including usage examples and return format. However, the minor inconsistencies (tool names without 'sd_' prefix, the 'ctx' arg, and redundant purpose) create slight gaps in 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 coverage is 0%, so the description compensates by explaining the 'year' parameter with an example (1785) and its meaning in the context of Schleiermacher's biography. However, it also lists 'ctx' as an argument, which is not in the input schema, potentially confusing the agent about required parameters.

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

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

The description clearly states the tool retrieves all chronology entries for a specific year, with a verb+resource structure. It also distinguishes from siblings by noting alternatives for specific dates, ranges, and keyword searches.

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 WHEN TO USE and WHEN NOT TO USE sections explicitly provide usage context, including example user queries, and name specific alternative tools for different scenarios (e.g., get_chronology_entry, get_chronology_entries, search_documents).

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?

No annotations are provided, so the description must convey behavior. It states that it returns a CollectionStats object and describes the collection parameter, implying a read-only operation. However, it does not explicitly deny side effects, mention permissions, or discuss limitations, so it is adequate but not comprehensive.

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, WHEN TO USE, Args, Returns) and no wasted words. It is compact yet informative, staying within a few 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?

For a tool with one parameter and an output schema, the description provides sufficient guidance for an agent to decide when and how to invoke it. It covers the main use cases, parameter meaning, and return type, making it a complete standalone 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 schema only defines a single string parameter with a default. The description adds critical context: 'collection' is a path relative to data_path, and an empty value represents the root collection. This fully compensates for the 0% schema description 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 opens with 'Get statistics about documents in a collection' and includes a PURPOSE section clarifying it measures size/content. This clearly distinguishes it from sibling tools like sd_list_collections or sd_list_collection_contents.

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 WHEN TO USE section gives concrete scenarios (e.g., 'how many documents are there?') and advises using it before browsing/searching. It does not explicitly state when not to use it or name alternative tools, so it is clear but lacks exclusionary 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?

With no annotations, the description carries the transparency burden. It communicates the read-only nature implicitly via 'statistics' and 'overview', and describes the return format. However, it does not explicitly state side effects, permissions, or limitations such as how results are ordered or what 'most important' means.

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-organized with PURPOSE, WHEN TO USE, Args, and Returns sections, making it scannable. Each section adds essential information with no redundant filler.

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

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

Given the tool's simple two-parameter interface and the presence of an output schema, the description covers purpose, usage scenarios, parameters, and return structure. It leaves some ambiguity about the meaning of 'most important' and the sorting order, but overall is sufficient.

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 (0% coverage), but the description's Args section explains 'year' as an optional filter and 'min_letters' as a minimum count, adding meaning beyond the bare type definitions. It could be clearer whether min_letters applies to total letters or each direction.

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 provides statistics about correspondents for network analysis, with a purpose of giving an overview of the most important correspondents. This distinguishes it from sibling tools like sd_get_collection_stats and sd_search_documents by focusing on correspondent-level aggregates.

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 'WHEN TO USE' section provides explicit scenarios, such as user asking about someone's importance or most frequent correspondents, and for quantitative analyses. It does not mention when not to use it or alternative tools, so it lacks exclusions.

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?

With no annotations, the description carries the full burden. It discloses important behavioral constraints: available years (1808-1811, 1817, 1820-1834) and explicitly notes non-extant periods (1812-1816, 1818-1819). It also describes the return format as a list of dicts with date, left_side, right_side content, giving the agent concrete 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?

The description is well-organized with clear sections (PURPOSE, Available years, WHEN TO USE, WHEN NOT TO USE, Args, Returns) that each serve a distinct function. Minor redundancy exists between the opening sentence and PURPOSE section, but overall it remains efficient and scannable.

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

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

For a simple range-retrieval tool with two parameters, the description covers all essential aspects: purpose, usage distinctions, data availability, parameter formats, and output structure. No critical information is missing that an agent would need to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It provides clear semantics for both parameters: ISO 8601 format (YYYY-MM-DD) for date_from and date_to, plus the `ctx` FastMCP context parameter. This fully resolves the meaning of each 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 opens with a specific verb+resource ('Retrieve diary entries') and defines the scope as a date range. It clearly distinguishes from sibling tools by explicitly noting when not to use it (single date or keyword search). This is a solid, unambiguous purpose statement.

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 includes explicit WHEN TO USE and WHEN NOT TO USE sections, naming specific alternatives: get_diary_entry() for single dates and search_in_documents() for keyword searches. This provides clear decision criteria for an agent.

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?

With no annotations, the description carries the burden. It adds valuable context about available years (1808-1811, 1817, 1820-1834) and missing years, plus the return structure (date, left/right content, raw XML). It doesn't mention behavior for invalid dates, but the limitations are well documented for a read-only retrieval.

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-organized into PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, and Returns. Each section is concise and purposeful without redundancy, making it easy to parse and act upon.

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 tool with an output schema, the description covers all necessary context: purpose, usage, exclusions, parameter format, and return structure. It is complete and self-sufficient for an agent to invoke 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 coverage is 0% for the date parameter, and the description fully compensates by specifying 'Date in ISO 8601 format (YYYY-MM-DD)' with an example. It also documents the ctx parameter, adding meaning beyond the bare 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 'Retrieve a specific diary entry by date' and further explains 'Access a specific day's entry from Schleiermacher's diary'. It distinguishes itself from sibling sd_get_diary_entries (plural) by explicitly noting this is for a specific date, not a range.

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 explicit WHEN TO USE cases (specific date, after search) and WHEN NOT TO USE cases, naming alternatives: 'use get_diary_entries()' for date ranges and 'use search_in_documents()' for keyword search. This gives clear decision 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?

With no annotations, the description carries the full burden. It discloses that the tool returns a 'Formatted markdown string with document content' and implies a read-only operation via 'Retrieve' and 'detailed view.' It lacks explicit safety/permission notes, but for a simple lookup tool this is sufficient 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 well-structured with clear section headers (PURPOSE, WHEN TO USE, etc.) and is front-loaded with the core action. No redundant sentences; each section contributes to understanding tool usage.

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 tool with an output schema, the description covers usage, input semantics, and output format. It also provides clear usage boundaries relative to siblings, making it complete within the given context.

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

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

Schema coverage is 0%, but the description adds meaning: 'document_id: The xml:id of the document.' This explains the semantic nature of the identifier beyond the bare parameter name, which is valuable given the otherwise sparse 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 'Retrieve complete document' and specifies 'Detailed view of a specific document as Markdown,' which is a specific verb+resource. It distinguishes from siblings like sd_get_raw_document_by_id and sd_get_diary_entry by emphasizing the 'complete' and 'Markdown' format.

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

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

Explicit WHEN TO USE and WHEN NOT TO USE sections provide clear context: reading letters/diary entries, after search, and for citations. It names specific alternatives (list_collections, search_by_keyword) for browsing and searching, which is excellent sibling differentiation.

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?

With no annotations provided, the description carries the full burden and explains key behavioral traits: query acts as a filter/highlight, division/page filter by @n, context_size controls context characters, and max_passages limits results. It also states the return type (Passage objects). It does not address error handling or side effects, but the read-only nature is clearly implied by 'Retrieve' and the parameter descriptions.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns) that are easy to parse. Despite being relatively long, every sentence provides actionable information, and the front-loading of purpose and usage makes it 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 six-parameter input schema, no annotations, and an existing output schema, the description covers all essential aspects: purpose, usage context, parameter semantics, and return behavior. It explicitly mentions the return type and provides enough context for correct tool 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?

The schema description coverage is 0%, so the description fully compensates by explaining every parameter: document_id is the xml:id, query is an optional search term, division filters by @n, page filters by pb/@n, context_size is characters of context, and max_passages is the maximum number of passages. These details add meaningful semantics beyond the raw schema.

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

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

The description clearly states the tool retrieves text passages from a specific document, distinguishing it from search and full-document retrieval by naming alternatives like get_document_by_id. It uses specific verbs and resource references, making the purpose unmistakable.

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

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

The description includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, providing concrete scenarios (after search returns document IDs, for reading sections, needing quotes) and naming alternative tools (search_documents_direct, get_document_by_id). This gives the agent clear guidance on tool 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?

No annotations are provided, so the description carries the full burden. It explicitly states the tool extracts metadata without full parsing, and the 'Returns' section details the exact output fields, making the tool's behavior transparent and setting 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?

The description is well-organized with clear headers (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns), making it easy to scan. Every sentence adds value, and it remains concise despite covering multiple aspects.

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

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

The tool is simple (one parameter) and has an output schema, but the description goes beyond by explaining purpose, usage, parameters, and return values. It covers all necessary context for correct tool invocation without redundancy.

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%, but the description fully explains the only parameter: 'file_path: Full path to the file (relative to /db) or just filename.' This adds crucial context beyond the bare schema, including path format and flexibility.

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: 'Get basic metadata for a single document file' and 'Extract basic TEI metadata from a document without full parsing.' This distinguishes it from sibling tools like sd_get_document_by_id and sd_get_raw_document_by_path, which likely provide full content.

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 'WHEN TO USE' section provides explicit scenarios (after browsing, when needing title/date/ID) and the 'WHEN NOT TO USE' section names alternatives: 'For full document content → use get_document tools' and 'For multiple files at once → use browse then call this for each.' This gives clear guidance and differentiates from peers.

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?

No annotations are provided, so the description carries the full burden. It discloses the output type (RawDocument with id and XML content), the parameter semantics, and mentions progress reporting via ctx. It doesn't discuss error cases or authorization requirements, but for a simple retrieval operation the disclosure is solid.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns). Every sentence adds value and there is no fluff or repetition of schema fields.

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 2-parameter read tool, the description is complete: it covers purpose, usage guidance, parameter details, and return type. The presence of an output schema means return values don't need extensive explanation, but the description still provides them.

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

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

The input schema has zero description coverage, but the description fully compensates by explaining each parameter: document_id is the TEI xml:id, collection is an optional filter relative to data_path, and ctx is for progress reporting. This adds meaning well beyond the bare schema.

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

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

The description opens with 'Retrieve raw XML document by its xml:id', which is a specific verb+resource+identifier. It clearly distinguishes this low-level raw retrieval tool from siblings like sd_get_document_by_id and sd_get_raw_document_by_path by emphasizing the TEI xml:id and raw XML nature.

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

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

Explicit WHEN TO USE and WHEN NOT TO USE sections list concrete scenarios (after search/browse, custom processing, building block) and explicitly direct users to sibling tools (browse/search for discovery, get_raw_document_by_path for file paths). This provides clear alternatives and exclusions.

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?

No annotations are provided, so the description must carry the behavioral burden. It discloses the return type (RawDocument with id, xml content, and path) and the path base (/db), but it does not mention error handling, permission requirements, or potential side effects. The mention of a 'ctx' parameter not in the schema adds slight ambiguity. Middle ground 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 well-structured with a summary, purpose, when-to-use, when-not-to-use, args, and returns sections. Each part serves a distinct informative purpose without redundancy. It is sufficiently detailed yet easy to scan, and the front-loaded summary ensures quick understanding.

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 one-parameter retrieval tool with an output schema, the description is nearly complete. It covers purpose, usage conditions, parameters, and return value. Minor gaps include lack of error context (e.g., path not found) and no explicit mention of read-only behavior, but these are not critical given the tool's simplicity.

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

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

The input schema has a bare 'doc_path' with no description (0% schema coverage). The description compensates by defining it as 'Path to the document (relative to /db)', adding crucial context. It also documents the ctx argument (though not in schema), which helps explain progress reporting. Clear value beyond the schema.

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

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

The opening sentence 'Retrieve raw XML document by its file path' uses a specific verb with resource and scope. It clearly distinguishes from siblings by naming the alternative 'get_raw_document_by_id()' and highlighting the path-based advantage, so it differentiates from other document retrieval 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 includes dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections with explicit conditions: use when a file path is known from browse_collection, avoid when xml:id is available (pointing to get_raw_document_by_id) and for exploration (recommending browse/search). This is exemplary 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the effect of include_mentions ('fetch mentions across letters, diaries, lectures') and max_mentions ('Max mentions per category'), and notes that return type varies by entry type. However, it doesn't disclose potential performance implications of fetching mentions or what happens when an entry_id is not found, so it stops short of full 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?

Despite being detailed, the description is well-structured with clear sections (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns). Every sentence carries informative content, no filler. The front-loaded purpose line immediately tells the agent what the tool does, and the subsequent sections earn their place.

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

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

The description covers purpose, usage conditions, parameter semantics, and return types ('PersonEntry, PlaceEntry, WorkEntry, or dict'). It even notes the existence of an output schema. Given the tool's moderate complexity (3 parameters, one required) and the presence of an output schema, the description is complete and self-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?

The input schema provides no descriptions (0% coverage), so the description must compensate. It thoroughly explains each parameter: entry_id with an example format, include_mentions with its effect, max_mentions with its default and behavior, and even the internal ctx parameter. This adds clear meaning beyond the bare 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 the tool's purpose: 'Get detailed information about a register entry' and elaborates with 'Complete register entry details, optionally with mentions.' It specifies the resource (register entry) and the action (get detailed information), and distinguishes from document-related tools by explicitly noting 'For document details → use get_document_by_id().' This effectively differentiates it from siblings with overlapping functions.

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 explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, giving concrete contexts such as 'After register search for details about a person/place/work' and 'For biographical information.' It also names the alternative tool for document details. This clearly guides the agent on when to select this tool over others.

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?

With no annotations, the description carries full behavioral disclosure. It mentions the non-parsing behavior, explains the collection path semantics ('Empty = root'), includes a context parameter for progress reporting, and states the return structure. It lacks error handling or sort order details, but for a listing tool this is adequate.

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, WHEN TO USE, WHEN NOT TO USE, Args, Returns). Each line adds value without redundancy, and the format is front-loaded with the core purpose before usage guidance.

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 tool's purpose, appropriate use and alternates, all parameters, and the return format, including the dict keys ('collection_path', 'file_count', 'files', 'subcollections'). It is complete for a listing tool with no annotations and simple schema.

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

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

Schema coverage is 0%, so the description must define parameters. It does so fully: collection as 'Collection name/path (relative to data_path). Empty = root.' and limit as 'Maximum number of files to return,' exceeding schema information. It also documents the ctx parameter, which is not in the schema.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List files and subcollections in a collection.' It also adds the distinguishing scope 'without parsing document contents,' which differentiates it from document-parsing siblings like sd_get_document_by_id.

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

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

Explicit WHEN TO USE and WHEN NOT TO USE sections provide clear guidance, naming specific alternatives: get_file_info for metadata, search tools for keyword search, and get_document tools for full details. This is a model example of when-to-use vs 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?

No annotations are provided, so the description carries the burden. It discloses the return structure (collection object with path, collections list, document_count) and the parent path meaning. However, it stops short of explicitly stating read-only behavior or any limitations, which would strengthen it. Since it's a simple list tool, this is adequate but not exceptional.

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 labels (PURPOSE, WHEN TO USE, Args, Returns) and front-loads the main purpose. No redundant text; each sentence serves a function.

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

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

Given the tool's simplicity, one parameter, and existing output schema, the description covers purpose, usage, parameter, and return shape. It fully equips the agent to 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 single parameter 'parent' is fully explained in the description: 'Parent collection path (relative to data_path). Empty = root.' This adds semantics beyond the bare schema, compensating for 0% schema 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 opens with 'List available sub-collections in the database' — a specific verb and resource. It explicitly states PURPOSE to explore database structure, which distinguishes it from sibling sd_list_collection_contents that lists contained items.

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 a dedicated WHEN TO USE section with clear scenarios such as 'User wants to know what data is available' and 'Finding the correct collection name for other queries.' While it doesn't explicitly name alternatives or exclusions, the context is well-defined.

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?

With no annotations, the description carries the full behavioral transparency burden. It goes well beyond a simple action statement by including a CITATION WARNING (never invent IDs/URLs, use exact values), explaining search logic (include_commentary, use_or_logic), mentioning the underlying eXist-db platform, and documenting the return fields (document_id, citation_url, etc.). This provides rich behavioral context for the agent, including a critical safety rule about citations.

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-organized with clear headings (PURPOSE, WHEN TO USE, WHEN NOT TO USE, CITATION WARNING, Valid doc_types, Args, Returns), making it easy to scan. It is verbose, though, with some redundancy: the opening one-liner 'Search documents...' repeats the PURPOSE, and the Valid doc_types list repeats the doc_types from Args while adding counts that may not be essential. Still, every section contributes value 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?

The description covers all 8 parameters, return format, citation handling, and usage context, which is highly complete for a search tool. The main omission is lack of comparison with the sibling mop_search_documents, which represents a contextual ambiguity. Additionally, the 'ctx' parameter is only mentioned as 'FastMCP Context' with no explanation, though its purpose may be obvious from the framework. These minor gaps prevent a perfect score.

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

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

The input schema has 0% description coverage, so the parameter explanations in the description are essential. The Args section defines every parameter with meaning and examples: query as space-separated terms, doc_types with allowed values, years as list, date_from/date_to with ISO 8601 format, include_commentary and use_or_logic booleans with defaults, and limit with default. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states 'Search documents in Schleiermacher Digital via eXist-db with facets' and elaborates with a PURPOSE section, naming the tool as the primary search tool for documents by text, type, year, etc. It distinguishes from several siblings in the WHEN NOT TO USE section (filter_letters, search_register, get_document_passages), but it does not differentiate from the sibling tool 'mop_search_documents', which has a nearly identical name and function. Thus it is clear but not fully distinguishing across the sibling set.

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 an explicit WHEN TO USE list (full-text search, filtering by type/year, any document discovery) and a WHEN NOT TO USE list naming three specific alternatives. However, it omits guidance on when to use mop_search_documents instead, which is a direct sibling likely serving a similar role. This leaves a gap in alternative selection, though the provided guidance is otherwise excellent.

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?

No annotations are provided, so the description carries the full burden. It discloses the Lucene fulltext index mechanism, the return format (list of dicts with id/title/desc/type), and implies read-only search behavior. It does not address edge cases like empty results or permission requirements, but for a search operation this is adequate context.

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-organized with PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, and Returns sections. Each section provides necessary guidance without redundancy, making the description both concise and informative.

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 usage triggers, exclusions, parameter meanings, and return shape comprehensively. An output schema exists, so the includes return list is not strictly necessary. It could further differentiate from the sibling mop_search_register, but this is a minor gap given the overall 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%, but the description explains all parameters: query as a search term, register_type with allowed values 'person', 'place', 'work', 'org', or None, and max_results as maximum results. It also adds the ctx parameter context. This fully compensates for the schema's lack of descriptions.

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

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

Description clearly states 'Search register using Lucene fulltext index' and PURPOSE explicitly identifies target entities (persons, places, works, organizations). It distinguishes from sibling fulltext search by naming the register 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?

WHEN TO USE bullets list concrete triggers and goals (searching by entity type, biographical/geographical info, getting IDs). WHEN NOT TO USE explicitly points to search_by_keyword() for fulltext search in letters/diaries, providing an alternative.

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