Server Quality Checklist

Tool Scores

• export_conceptA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It states the tool exports and returns the concept in the requested format or an error message, which is useful. It does not mention side effects, permissions, or read-only status, but export inherently implies a non-destructive operation.

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

  Conciseness5/5

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

  The description is short, front-loaded with the main purpose, and structured into Args and Returns sections. Every sentence contributes useful information without redundancy.

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

  Completeness4/5

  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 is complete enough: it covers the purpose, parameters, and return behavior. It lacks usage comparisons with siblings, but that is already captured in the usage guideline dimension.

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

  Parameters4/5

  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 iri as 'The concept IRI or identifier' and enumerating the allowed format values ('markdown', 'jsonld', 'owl_xml'). This adds meaningful value beyond the bare schema.

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

  Purpose5/5

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

  The description clearly states the tool exports a FOLIO concept in a specific format, with an explicit list of supported formats. This distinguishes it from sibling tools like get_concept, which likely returns concept data without format conversion.

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

  Usage Guidelines3/5

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

  Usage is implied: use this when you need a concept in markdown, JSON-LD, or OWL/XML. However, it does not explicitly contrast with alternatives such as get_concept or query_concepts, nor does it state when not to use this tool.

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

• get_conceptA
  4.1/5.0
  Behavior4/5

  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 goes beyond a bare 'get by IRI' by specifying the accepted input formats, the return type (full JSON representation), and error behavior. However, it doesn't clarify what happens with ambiguous partial matches or any auth/permission requirements, leaving some room for improvement.

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

  Conciseness4/5

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

  The description is well-structured and front-loaded: it opens with the purpose, then provides examples, and closes with Args/Returns sections. Every sentence contributes useful information. It is slightly verbose with the examples, but they are relevant and aid understanding.

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

  Completeness4/5

  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 adequately covers the input forms and the shape of the return, including an error message case. It could be more complete by explaining the behavior of partial matches or noting any prerequisites, but it is sufficient for the tool's simplicity.

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

  Parameters4/5

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

  The schema has only a string property with a required field and no description (0% coverage), so the description must compensate. It does this effectively by explaining that 'iri' accepts short IDs, full IRIs, or partial matches, with concrete examples. This adds meaningful semantic context beyond the schema, though it could specify constraints like URL encoding or case sensitivity.

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

  Purpose5/5

  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 full details for a specific FOLIO concept by IRI.' It uses a specific verb ('Get') and resource ('FOLIO concept'), and the method (by IRI) distinguishes it from siblings like search_concepts and list_branches, which focus on search or enumeration. This is a clear and distinct purpose.

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

  Usage Guidelines3/5

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

  The description provides input format guidance—short IDs, full IRIs, partial matches—but does not explicitly state when to use this tool versus the many alternatives. The usage is implied rather than articulated. There is no mention of 'use this when you have an identifier, search when you don't,' so it does not fully guide the agent on tool selection.

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

• get_propertiesA
  4.1/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of disclosing behavior. It explains the return format (JSON array with iri, label, definition, domain, range) and gives examples, but does not explicitly state read-only status, permissions, or potential limitations. The behavior is implied by 'get' but not fully transparent.

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

  Conciseness5/5

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

  The description is concise and well-structured: the first sentence states the primary purpose, followed by a clear return specification. Every sentence adds value and there is no redundancy.

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

  Completeness5/5

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

  Given the tool has no parameters and the description explicitly details the output fields, the description is fully complete for an agent to select and invoke the tool. There are no missing behavioral or required contextual details for this simple read operation.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline of 4 applies. The description does not need to elaborate on parameter semantics, and the schema already shows an empty parameter list.

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

  Purpose5/5

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

  The description uses a specific verb 'Get all' with a clear resource 'OWL object properties' and provides examples (hasJurisdiction, appliesTo). This distinguishes it from sibling tools like query_properties, which presumably handle targeted queries rather than full listings.

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

  Usage Guidelines3/5

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

  The description implies usage when one needs the complete set of object properties, but it does not explicitly state when to prefer this over alternatives like query_properties or provide any exclusions. Usage context is implied, not elaborated.

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

• find_connectionsA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description must disclose behavior itself. It accurately describes the return format (JSON array of triples with subject/property/object objects) and filtering behavior. However, it omits potential caveats such as pagination, result limits, or error handling, making it minimal but not misleading.

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

  Conciseness5/5

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

  The description is tight and well-structured: a one-sentence summary, a paragraph on search behavior, an Args list, and a Returns line. Every sentence adds value, and the most important information is front-loaded.

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

  Completeness4/5

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

  Given the tool's simplicity and the existence of an output schema, the description covers essential aspects: what the tool does, required and optional parameters, and the return shape. It omits edge-case behavior (e.g., no results, invalid IRI), but this is a minor gap for a read-only query tool.

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

  Parameters4/5

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

  Since the schema has 0% parameter description coverage, the description compensates by explaining each parameter: subject_iri as the IRI of the subject concept, property_name as an optional filter, and object_iri as an optional object IRI. This adds meaningful semantics beyond the bare schema types and names.

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

  Purpose5/5

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

  The description clearly states the tool finds/ searches for semantic connections (triples) between FOLIO concepts. It uses specific verbs ('Find', 'Searches') and describes the resource as subject-property-object triples, which distinguishes it from sibling tools like get_children or get_parents.

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

  Usage Guidelines4/5

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

  The description clearly indicates that a subject_iri is required and that property_name and object_iri are optional filters. This gives clear context on how to invoke the tool. However, it does not explicitly mention when to prefer this over alternative tools or provide exclusions, 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.

• list_branchesA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the return format (JSON mapping branch names to concept counts) and scopes the result to the 24 top-level categories. It does not explicitly mention side effects or permissions, but 'list' inherently indicates a read-only operation.

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

  Conciseness5/5

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

  The description is compact and front-loaded with the core purpose in the first sentence. The supporting details (24 categories, examples, return format) are concise and every sentence adds value.

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

  Completeness5/5

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

  For a zero-parameter read-only tool with an output schema, this description is complete. It explains what the tool returns, the scope of results, and gives concrete examples. No critical information seems missing for an agent to invoke it correctly.

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

  Parameters4/5

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

  The tool takes zero parameters, so there is nothing to explain beyond what the empty input schema shows. The description adds meaningful context about what the output contains, which is sufficient given the lack of parameters.

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

  Purpose5/5

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

  The description clearly states the tool lists all FOLIO taxonomy branches with concept counts. It specifies the exact scope (24 top-level categories) and provides examples, differentiating it from sibling get_taxonomy_branch which presumably fetches a single branch.

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

  Usage Guidelines3/5

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

  The description implies usage when an overview of all taxonomy branches is needed, but it does not explicitly mention when to use this tool over alternatives like get_taxonomy_branch or search_concepts. No when-not-to-use guidance is provided.

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

• search_conceptsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses fuzzy matching behavior, the limit parameter's default, and the return structure (JSON array with specific fields). It does not detail edge cases or error behavior, but for a search tool this is reasonable transparency.

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

  Conciseness5/5

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

  The description is concise and well-structured: a one-line summary, a clarifying sentence, then Args/Returns sections. Every sentence adds useful information, with no fluff or repetition beyond minor overlap in the first two sentences.

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

  Completeness4/5

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

  The tool is simple with two parameters, and the description covers both parameters, the fuzzy matching approach, and the return format. It lacks explicit discussion of no-result scenarios or pagination beyond the limit, but given the tool's simplicity, the description is largely complete.

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

  Parameters5/5

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

  Schema coverage is 0% in the context signals, so the description is the only source of parameter meaning. It explains 'query' with concrete examples and 'limit' with its default, adding significant value beyond the bare schema types.

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

  Purpose5/5

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

  The description clearly states the tool searches FOLIO concepts by label/name, using a specific verb and resource. It further specifies fuzzy matching and positions itself as the primary entry point for finding concepts, distinguishing it from siblings such as search_definitions and get_concept.

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

  Usage Guidelines4/5

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

  The description provides clear context by stating 'Use this as the primary entry point for finding concepts,' which indicates when to use it. However, it does not explicitly mention alternatives or when not to use it, so it lacks full exclusion/alternative guidance.

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

• search_definitionsA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden for behavioral disclosure. It explains the return format ('JSON array of matching concepts with iri, label, definition, and score') and the default limit, which adds useful context beyond the schema. However, it does not mention nuances such as case sensitivity, matching semantics, or error behavior, leaving some room for improvement.

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

  Conciseness5/5

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

  The description is well-structured with a clear opening sentence, an explicit usage hint, and labeled 'Args:' and 'Returns:' sections. Every sentence contributes valuable information without unnecessary padding, making it highly concise and front-loaded.

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

  Completeness5/5

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

  For a relatively simple search tool with an output schema and only two parameters, the description covers all essential aspects: purpose, when to use, parameter meanings, and return value. It is complete for the tool's complexity, and no critical gaps are evident.

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

  Parameters4/5

  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 by clarifying that 'query' is the search term to match against definitions and that 'limit' is the maximum number of results, which adds meaning beyond the bare schema titles. The explanation is sufficient, though not exhaustive.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Search FOLIO concepts by definition text' and 'Finds legal concepts whose definitions match the query.' It uses a specific verb and resource, and differentiates from name-based search by explicitly referencing the search target as definitions.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool: 'Use this when searching by name doesn't find what you need.' It implies an alternative (name search) but does not explicitly name a sibling tool or specify when not to use it, so it falls short of the explicit exclusions expected for a score of 5.

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

• query_conceptsA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses AND logic, filter semantics (e.g., transitive subClassOf for parent_iri, leaf vs non-leaf for has_children), defaults for deprecated and match_mode, and the return format. It does not cover error handling or performance, but for a query tool the disclosed behaviors are substantial.

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

  Conciseness5/5

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

  The description opens with a clear purpose, then uses well-organized bullet sections for text filters, structural filters, control, and returns. Every sentence is informative, and the structure makes it easy to scan. It is detailed without wasting words.

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

  Completeness5/5

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

  The tool is complex with 12 parameters, but the description covers all of them with meaningful context. It explains the overall AND logic, default behaviors, and return type. The output schema is said to exist, so not detailing the exact return structure is acceptable. The description is sufficiently complete for an agent to correctly invoke the tool.

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

  Parameters5/5

  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 compensate. It does so by explaining each parameter's meaning, including RDF properties (rdfs:label, skos:definition), providing branch examples, and defining match_mode values. This adds significant value beyond the raw schema.

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

  Purpose5/5

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

  The description clearly states the tool queries FOLIO concepts with composable filters. It explicitly differentiates from sibling search_concepts by positioning itself as more powerful and supporting field-specific matching, structural constraints, and multiple match modes.

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

  Usage Guidelines4/5

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

  The description explains the tool's capabilities and contrasts it with search_concepts, giving context for when to use it. However, it does not explicitly state when to use the simpler sibling tool, so the guidance is context-rich but lacks explicit exclusions or alternatives beyond a comparative phrase.

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

• query_propertiesA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description must disclose behavioral traits on its own. It does this well by detailing the supported filter types, match modes, and return format ('JSON array of matching properties'). However, it does not explicitly state that the operation is read-only, nor does it describe edge cases (e.g., behavior when no filters are supplied) or performance implications, leaving some behavioral gaps.

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

  Conciseness5/5

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

  The description is well-structured with clear sections: a one-sentence summary, the usage distinction, filter categories, control parameters, and return format. Every sentence carries useful information and the front-loaded opening makes it easy to understand the tool's core purpose quickly. It is appropriately sized for a tool with seven parameters.

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

  Completeness4/5

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

  The description is comprehensive for a query tool: it explains the tool's purpose, when to use it, all parameter semantics, and the return shape. The existence of an output schema reduces the need to detail return values, but the description still provides a helpful summary. A minor gap: it does not explicitly state what happens when no filters are provided (likely returns a full list), which would strengthen completeness. Overall, it is complete enough but not exhaustive.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description compensates fully by explaining each parameter semantically. It gives examples for label (e.g., 'jurisdiction', 'applies'), clarifies match_mode options ('substring', 'exact', 'regex', 'fuzzy'), and defines has_inverse with boolean semantics. This adds significant meaning beyond the raw schema.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Query FOLIO object properties with composable text and structural filters.' It also differentiates from the sibling tool get_properties by explicitly noting it 'Replaces get_properties() when you need filtered results instead of the full list,' which is a specific verb+resource+scope that distinguishes it.

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

  Usage Guidelines5/5

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

  Provides explicit guidance: 'Replaces get_properties() when you need filtered results instead of the full list.' This names an alternative and states the condition for using this tool over that alternative, which exceeds the minimum requirement for usage guidance.

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

• get_childrenA
  4.8/5.0
  Behavior4/5

  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 compact summaries, explains the input format (IRI or short ID), and warns against branch names. It also specifies the return structure as a JSON array. However, it does not explicitly state that the tool is read-only/non-destructive, though the 'Get' verb implies this.

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

  Conciseness5/5

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

  The description is concise and front-loaded: a one-sentence summary followed by labeled Args and Returns sections. Every line adds value, including the branch-name warning and the max_depth recommendation. No filler or redundancy.

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

  Completeness5/5

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

  For a simple tool with two parameters and no annotations, this description covers purpose, parameter semantics, return format, and alternatives. It also includes a practical hint about result size. The guidance is sufficient for an agent to invoke the tool correctly without additional context.

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

  Parameters5/5

  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 thoroughly explains the iri parameter with examples and an exclusion (not a branch name), and describes max_depth with its default and a performance suggestion. This adds significant meaning beyond the raw schema.

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

  Purpose5/5

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

  The description opens with 'Get child concepts of a FOLIO concept,' clearly specifying the verb and resource. It also distinguishes itself from siblings like get_taxonomy_branch and get_concept, making its purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description explicitly tells users what not to do: 'NOT a branch name — use get_taxonomy_branch for branch names.' It also advises keeping max_depth at 1-2 to avoid large results and directs users to get_concept for full details, providing clear alternatives.

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

• get_parentsA
  4.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full transparency burden. It discloses the return format ('JSON array of {iri, label, definition} summaries') and the compact nature of results, plus the constraint that iri is not a branch name. However, it does not mention error behaviors, rate limits, or explicitly state read-only semantics, which would make it a 5. Still, it provides substantial behavioral context 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.

  Conciseness5/5

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

  The description is front-loaded with the primary purpose, followed by clearly labeled Args and Returns sections. Every sentence contributes useful information: the IRI example, the branch-name exclusion, the depth default, and the pointer to get_concept. No filler or redundancy.

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

  Completeness5/5

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

  Given the tool's simplicity (2 params, 1 required) and the existence of an output schema (implied by the description's return format), the description fully covers the needed context. It explains what the tool does, how to use it, what the parameters mean, what the response looks like, and where to go for full details. This is complete for a read-only traversal tool.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description is the sole source of parameter meaning. It thoroughly explains iri with an example IRI and the 'NOT a branch name' clarification, and it defines max_depth as 'Depth limit (default 1 for direct parents).' This adds significant value beyond the bare schema properties and default value.

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

  Purpose5/5

  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: 'Get parent concepts of a FOLIO concept.' It clearly distinguishes from siblings like get_children and get_concept by focusing on parent traversal and compact summaries. The 'Returns compact summaries' line further differentiates it from get_concept's full details.

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

  Usage Guidelines5/5

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

  The description explicitly states 'NOT a branch name,' which prevents a common misuse. It also provides a direct alternative: 'Use get_concept(iri) for full details on a specific parent.' The context for max_depth ('default 1 for direct parents') tells the user how to control depth, giving clear usage guidance.

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

• get_taxonomy_branchA
  4.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that results are 'compact summaries' of {iri, label, definition}, warns that 'depth >2 can return very large results,' and recommends incremental navigation. This covers key behavioral traits like performance impact and return format. It falls short of a 5 only because it does not mention potential errors or edge cases (e.g., invalid branch name), but it is still notably transparent for an unannotated 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.

  Conciseness5/5

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

  The description is front-loaded with a clear one-sentence summary, followed by well-organized 'Args' and 'Returns' sections. Every sentence provides necessary information without redundancy. It is concise yet complete, using structural elements like warnings and cross-references efficiently.

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

  Completeness5/5

  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 schema and the presence of an output schema, the description covers all essential aspects: purpose, parameters, return format, performance caveats, and cross-tool navigation. It provides enough context for an AI agent to use the tool correctly without missing information.

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

  Parameters5/5

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

  The input schema has 0% description coverage, so the description must fully compensate. It explains branch_name with an example and directs users to list_branches(), and explains max_depth with a default, a use case (1 for top-level), and a warning about depth >2. This adds substantial meaning beyond the raw schema properties, entirely covering the parameter semantics.

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

  Purpose5/5

  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 concepts in a FOLIO taxonomy branch.' It specifies the resource (taxonomy branch) and the action (get), and distinguishes itself from siblings like get_children and get_concept by noting it returns compact summaries. This makes the tool's scope and differentiation immediately apparent.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool versus alternatives: 'Use list_branches() to see all available branch names,' 'Navigate incrementally with get_children() instead,' and 'Use get_concept(iri) for full details on a specific concept.' This clearly sets usage context and alternatives, which fully satisfies the dimension.

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