Server Quality Checklist

Tool Scores

• get_changelogA
  4.2/5.0
  Behavior3/5

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

  Annotations already cover readOnly, idempotent, and non-destructive behavior, so the description doesn't need to restate safety. It adds useful semantic context about the time fields and how they differ from get_stats, but it does not disclose other behavioral traits such as pagination, volume of log data, or any potential rate limits. The context added is helpful but modest.

  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?

  Two tightly packed sentences say exactly what the agent needs. The first sentence states what is returned; the second gives a sharp use case and contrasts with the sibling tool. No redundancy, no filler, and the guidance is 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?

  Given that there are no parameters, the presence of an output schema, and annotations covering the safety profile, the description supplies the remaining critical context: what bundleGenerated means, how to use it, and why get_stats's generated field is not equivalent. There is no missing information that would prevent a competent agent from invoking take this tool 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?

  There are 0 parameters, and the schema description coverage is 100% by default, so the parameter baseline is 4. The description does not need to compensate beyond that, and it instead correctly spends effort on clarifying the output field semantics.

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

  Purpose4/5

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

  The description clearly identifies the resource returned — the knowledge base's own log file and actual ingestion time. It distinguishes the tool from get_stats by contrasting `bundleGenerated` with the `generated` field, so an agent can tell them apart. It lacks an explicit verb like 'returns' or 'provides', but the intent is unmistakable.

  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 directs when to use this tool: 'Use `bundleGenerated` to answer how current this is or to cite a version.' It also directly names get_stats as an alternative and explains why its `generated` field is not the right source for data recency. This is clear when-and-when-not guidance.

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

• get_tagsA
  4.2/5.0
  Behavior4/5

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

  Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: the result is an aggregated count of documents per tag, sorted most-common-first, and tags cross collections rather than being scoped to one collection. This enriches the agent's expectation of tool behavior without contradicting the annotations.

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

  Conciseness5/5

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

  Two concise sentences deliver the core value proposition, example tag values, and the cross-tool filter use case. There is no fluff or repetition of annotation information, and the most important fact — returns tagged counts sorted by frequency — 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 presence of an output schema and clear annotations, the description is sufficiently complete. It covers the tool's output semantics, ordering, cross-collection scope, and downstream usage. It does not discuss pagination behavior, but the input schema's limit and offset descriptions already cover that.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear descriptions for limit and offset already provided in the schema. The description does not add material parameter semantics beyond the schema; it only reinforces the sorting order already present in the offset parameter description. Baseline 3 is appropriate since the schema carries the weight.

  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 this returns every tag in the bundle with the number of documents carrying it, ordered by frequency. It gives concrete examples of tag values, which makes the resource unmistakable, and differentiates it from sibling list/search tools by focusing on the tag vocabulary itself.

  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 that tags from this tool can be passed to search_concepts or list_documents to filter by them, giving an explicit downstream use case. It does not explicitly say when to avoid this tool or name an alternative for vocabulary lookup, but the filtering guidance is strong enough to guide an agent.

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

• find_places_nearA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description goes beyond annotations by warning that many coordinates are tentatively identified and advising users to check contested and identifications fields, which is valuable behavior context. It does not cover pagination or full view of return shape, but output schema exists.

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

  Conciseness5/5

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

  The description is succinct: behavior, ordering, distance unit, anchor approach, and a concrete caution are each packed into three tight sentences. It is front-loaded with the primary output and utility, and every clause earns its place.

  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?

  With output schema, 100% parameter descriptions, and clear read-only annotations, the description needs only to add usage nuance and caveats. It does exactly that, including the tentative identification warning that materially affects interpretation of results. An agent has sufficient information 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.

  Parameters3/5

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

  Schema coverage is 100%, and each parameter already has meaningful descriptions. The tool description clarifies the general anchor modes (place vs latitude/longitude) but does not add significant semantic detail beyond what the schema already provides. This is the correct baseline for fully-documented 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 identifies the specific operation: finding biblical places within a radius, ordered nearest first, with distance in kilometers. It clearly distinguishes this from generic search tools by emphasizing spatial proximity and coordinate/place anchoring. The intent is unambiguous and not a restatement of the name.

  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 explicit guidance on when to anchor by a known place versus using raw coordinates, including the specific use case for modern locations not in the knowledge base. It does not explicitly mention sibling alternatives or say 'use this instead of X,' so it does not fully satisfy the alternative-routing criterion.

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

• get_interlinearA
  4.3/5.0
  Behavior5/5

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

  Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds substantial behavioral context: what each entry contains, when lexeme is present, the lack of a Greek lexicon and incomplete Strong's coverage, and the specific five-verse limitation due to Berean edition disagreements. This goes well beyond the structured annotations.

  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 first sentence is a clear and immediate statement of the tool's purpose. Every subsequent sentence earns its place by explaining reverse-interlinear ordering, entry fields, lexeme availability, lexicon limitations, and a known data gap. It is dense without being wasteful.

  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 tool with one parameter, clear output schema presence, and annotations, the description covers everything an agent needs: what to pass, what it returns, what the limits of the data are, and where to find more detail about exceptions. No important operational context is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the osis parameter already described as a verse or chapter reference and examples provided. The description reinforces this by mentioning 'one verse or a whole chapter.' It adds meaningful context about the input's scope, but since the schema already carries the core parameter semantics, the baseline of 3 is appropriate.

  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: retrieving Hebrew, Aramaic, or Greek words behind the English word-by-word, for either a verse or a whole chapter. The phrase 'REVERSE interlinear' and the emphasis on tracing English words back to their source distinguish it clearly from the surrounding scripture/searching tools.

  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 clearly implies the tool is for original-language analysis of a single verse or chapter, and the schema enforces an OSIS reference. However, it does not explicitly contrast it with sibling tools like get_passage or get_vocabulary, nor does it state when one would prefer this over an alternative, so usage guidance beyond scope is mostly implied.

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

• search_scriptureA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description then adds valuable behavioral semantics: all words must appear in the same verse, double-quoted phrases require adjacency, results are ranked by how much of the verse matches, and short exact matches rank first. These are behavioral facts the schema and annotations cannot infer.

  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 tightly written and front-loaded. Each sentence earns its place: the first defines scope, the second gives a concrete use case, and the remaining sentences explain query matching behavior and ranking. There is no wasted prose or repetition.

  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?

  Considering the output schema exists to describe return values and the input schema covers all parameters, the free-text description is sufficient for correct invocation. It tells the agent the corpus, the query syntax, ranking behavior, and the best conditions for limiting results. The only minor omission is explicit alternatives, which purpose and usage clarity largely handle anyway.

  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 100%, so each parameter already has adequate documentation. The description adds meaningful query-level guidance beyond the parameter descriptions: same-verse matching, quoted-phrase behavior, and the ranking implication for short queries. It does not need to restate each parameter description.

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

  Purpose4/5

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

  The description clearly defines a precise task: full-text search over the 31,102 verses of the Berean Standard Bible and frames it as the way to find a half-remembered passage. It is unambiguous about the resource, but it does not explicitly differentiate itself from sibling tools such as the generic 'search' or 'get_passage', so it falls just short of perfect sibling distinction.

  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 strong usage context: 'This is how you find a passage you can half-remember but cannot cite' and gives actionable guidance to restrict by book or testament when a common word over-matches. It does not explicitly state when not to use this tool in favor of alternatives, so there is a small gap in exclusions.

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

• get_graph_neighborhoodA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare the operation read-only, idempotent, and non-destructive; the description goes beyond these by explaining that the response includes edges and predicates, not just nodes. It also warns about the cost of deeper traversal ('depth 3 gets large quickly and is capped') and points to get_vocabulary for predicate semantics, which is useful operational context.

  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?

  Three concise sentences, each carrying useful information: the main function, the filtering techniques, and the expectations about depth. No filler or redundant wording; the formatting with occasional capitals is minor.

  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?

  Without being verbose, the description covers all critical context an agent needs to make a correct invocation: what is returned, how to filter, how depth affects cost, and where to look up predicate meanings. The output schema and comprehensiveness annotation cover the remaining details, so nothing essential is missing.

  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 100% parameter description coverage, the baseline is 3, but the description adds meaningful semantic depth: type is used to 'ask a shaped question,' predicate narrows the graph to one kind of edge, and depth is contextualized as ranging from direct links to a fast-fan-out cap. These are real interpretation gains beyond the schema's literal field descriptions.

  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 explicitly defines the tool as returning everything within N hops of a document along with the connecting edges and their predicates. It clearly states the resource (graph neighborhood) and the action (get/traverse), making the tool’s behavior distinct from simple document fetches or direct-connection lookups.

  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 gives practical context for when to use the tool: asking what a passage, person, or theme is connected to without fetching each document. It explains how filtering by type and predicate can shape the query and warns about frontier growth, but it does not explicitly name or contrast siblings like get_connections or get_family, so the guidance is not exhaustive.

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

• get_connectionsA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds useful behavioral context: the three invocation modes and the kind of result each produces (totals, hubs, book-to-book pairs, rows, rank/vote weight). It does not address edge cases like mutually exclusive parameters, but that 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.

  Conciseness4/5

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

  The description is three sentences with no filler. The first sentence establishes the tool's conceptual scope, the second explains the three invocation modes, and the third provides the sibling routing. It is slightly verbose in phrasing ('Questions about the SHAPE...') but remains compact and well-organized.

  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 has a rich output schema, all three parameters are described in the schema, and the description covers the no-argument, book, and osis cases plus the alternative tool to use. Nothing needed for correct selection is missing: an agent knows what to expect, what parameters to pass, and which sibling to prefer.

  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 100%, so a baseline of 3 applies. The description goes beyond the schema by linking each parameter to a specific behavior: 'book' produces incoming/outgoing rows, 'osis' produces rank and vote weight, and no argument returns totals and top-ranked items. This adds real selection 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 states a specific verb, resource, and scope: it returns aggregate shape-of-the-corpus analytics for cross-references rather than per-verse references. It distinguishes itself from find_cross_references, which retrieves actual references, so an agent can select it without inspecting the schema.

  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 gives explicit conditions for each invocation mode: no argument for global totals/hubs, book for one book's rows, osis for a chapter's rank/vote weight. It names the sibling find_cross_references as the alternative and states the exact criterion for when to use it instead (getting actual references for a passage).

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

• get_entityA
  4.6/5.0
  Behavior5/5

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

  Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is already covered, and the description adds substantial complementary behavior: relations are returned in both directions but stored only on one side (so relations.inbound alone recovers a person's parents), the body contains content available nowhere else, numbered paths disambiguate duplicate names, and collection paths return collection contents. This genuinely recounts traversal semantics the annotations cannot convey, with zero contradiction.

  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 long, but nearly every line earns its place: the path catalog is actionable, the inbound-direction paragraph explains a genuinely hidden gotcha, the body sentence prevents a common mistake, and the disambiguation sentence routes to search_concepts. The opening line front-loads the core purpose before any detail, giving a well-ordered, efficient structure despite its length.

  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?

  With an output schema present, the description correctly avoids re-documenting return fields and instead fills the gaps: edge cases (duplicate names), a domain-specific data model quirk (one-side-only relation storage), body-attribution semantics, and collection-style paths. For a graph/document retrieval tool of this complexity, there is no mission-critical information an agent needs that is missing.

  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 100% for the 3 parameters, so the baseline is 3, but the description adds real semantic value for `path` — concretisized path examples, numbering rule, and collection-path behavior — and for `body`, explaining what kind of content lives in the prose and why one would request it. The reason for the backlinks parameter, by contrast, is already fully captured in the schema. The added semantics justify a 4.

  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 ('Fetch') plus a clear resource ('any document in the knowledge base by path') and then disambiguates that scope with 12 concrete path patterns spanning People, Places, Themes, Lexemes, and more. It actively differentiates itself from siblings by naming search_concepts as the alternative for resolving ambiguous paths. This makes the tool's role unmistakable relative to get_passage, search_scripture, and list_documents.

  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 gives explicit routing guidance: use search_consensus-like search_concepts first when a path might be ambiguous, set body=true when the target prose (Strong's definitions, Hebrew, outlines) is needed, and expect collection paths to behave differently. It clearly states the precondition for correct use (the/numbered path) but does not enumerate exclusions for every sibling tool.

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

• get_statsA
  4.6/5.0
  Behavior4/5

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

  Annotations already establish that this is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by detailing the catalogue contents and emphasizing that it is a discovery/mapping tool rather than a targeted search tool. No contradiction with annotations exists.

  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 concise and front-loaded with the essential label 'The catalogue'. It packs a lot of useful specifics into two sentences without excessive verbosity, although the phrasing is slightly list-heavy.

  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 overview tool, the description fully explains both return content and usage context. The presence of an output schema also reduces the burden of describing return structures. Nothing essential is missing.

  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?

  This tool takes zero parameters, so there are no parameter semantics to document. The description also does not need to compensate for schema gaps because there are no 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 identifies this as 'The catalogue' and enumerates precisely what it provides: collections, document counts, folder paths, graph totals, tags, and licences. It positions itself as the map to every other tool, distinguishing it from the specific data-fetching siblings.

  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 gives explicit situational guidance: 'Call this first if you do not know what the knowledge base holds'. This tells the agent exactly when to use it, and referring to it as the map to every other tool implies it is the entry point before others.

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

• get_vocabularyA
  4.6/5.0
  Behavior5/5

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

  With readonly/idempotent/destructive annotations already present, the description still adds valuable non-obvious behavior: relations are stored one-directionally, so a raw relation array always reads outward from the fetched document. This directly affects how an agent would interpret any relation data and is not encoded in the schema or annotations.

  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 front-loaded with the core purpose and then adds the canon table and a critical directionality note. It uses a dense first sentence with a long list and em-dashed asides, making it slightly heavy to parse, but every clause is informative and nothing it wastes 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?

  Given the tool's care, the description fully covers the available data: predicates, inverses, types, edge counts, canon table structure, and the important usage read-world directionality. The inclusion of a concrete exam seat ('Song of Songs is "Song"') and the instruction to read it before interpreting predicates make it complete even though a schema exists.

  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 input schema has zero parameters, so there is no parameter meaning to clarify. The baseline for 0 params is 4, and the description does not need to add extra param explanation. It does convey some contextual value by explaining how to use the canon table, but that lies outside 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 identifies the resource as the closed set of graph predicates, listing examples (develops, narrated-in, involves), their inverses, connected types, and edge counts. It also names the canon table with OSIS IDs, slugs, and chapter counts. This makes the tool's unique role as a reference vocabulary unambiguous and distinguishes it from sibling graph-query tools.

  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 states 'Read this before interpreting a predicate' and before building a reference, which gives a clear when-to-use trigger. It does not explicitly name alternatives or describe when not to use this tool, but the context makes it evident this is the reference lookup rather than one of the graph traversal or document retrieval tools.

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

• list_documentsA
  4.6/5.0
  Behavior5/5

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

  The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds valuable behavioral detail beyond that: ordering rules per collection, pagination behavior, folder aliasing semantics, and the note that the response reports total and whether more remain. This helps an agent anticipate both output and edge cases.

  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 detailed but every sentence contributes, from examples to ordering semantics to the pagination contract. The collection enumeration is slightly bulky but serves as immediate, actionable context for the `type` parameter. It is efficiently structured and not repetitive.

  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 list tool, the description covers all needed behaviors: default ordering, pagination, the full collection list, special folder-ish scoping, and the nature of the response. The annotation and 100% schema coverage already handle what happens on the mutation and parameter validation side, so nothing necessary to correctly invoke this tool is missing.

  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 100%, so the baseline is 3, but the description adds meaningful extra context: it explains that plurals and folder paths work as type values, clarifies the rationale for using `folder` when `type` cannot express a path, and connects `sort` values to real-world behavior (e.g., chronological for events/epochs). This goes beyond the schema descriptions without simply repeating them.

  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 states a specific action ('Browse and page') on a specific resource ('any collection in the knowledge base') and clearly contrasts with 'look one thing up', which distinguishes it from tools like get_entity and get_passage. It also lists concrete example queries, making what the tool does unmistakable.

  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 says when to use it—'when you want to know WHAT EXISTS'—and gives concrete examples like 'what events are recorded'. It names the alternative use case ('look one thing up') but does not explicitly name sibling tools, so it stops short of a fully explicit when-not/alternatives list.

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

• find_cross_referencesA
  4.7/5.0
  Behavior5/5

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

  Annotations already establish readOnly/idempotent/non-destructive behavior; the description adds valuable behavioral detail on top: results are ordered by crowd support, the corpus never records why passages are connected, and chapter-level documents are pre-materialized with a 20-vote floor. It also flaggers the surprising consequence that lowering minVotes does not broaden results, which materially shapes an agent's expectations.

  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 dense but every sentence earns its place: the first states purpose and ordering, the second prevents a false inference about edges between passages, and the third sets correct expectations about the minVotes threshold. Information is front-loaded and there is no redundant restatement of the title.

  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 presence of an output schema, complete parameter docs, a set of safety annotations, and only three parameters, this description covers everything an agent needs to call the tool correctly. The additional corpus-size/dataset hint also gives helpful awareness when a full cross-reference set is required rather than just a query result.

  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 100% and already documents OSIS, limit default/cap, and minVotes bounds. The description goes beyond the baseline by explaining the real-world effect on minVotes: a value below 20 will not change chapter output because lower references were filtered when the corpus was materialized. This is useful guidance that the schema alone could not provide.

  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 states a specific resource ('cross references') with a clear verb ('find') and scopes it as being for a verse or chapter, ordered by crowd support. It also distinguishes this tool from generic connection tools by clarifying these references have no recorded relationship type, so an agent will not confuse it with get_connections or get_graph_neighborhood.

  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 practical context, especially the Chapter level materialization floor of 20 votes and the caveat that lowering minVotes will not widen results. It does not explicitly name sibling tools or tell the agent when to choose this over get_connections or other graph-related 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.

• get_passageA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent annotations, the description adds genuinely useful behavior: text is the Berean Standard Bible, sixteen verses intentionally return empty text but keep their verse numbers, and the returned context includes speakers, places, people, themes, cross references, and back-references. This explains quirks an agent would otherwise discover by failure.

  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 action and examples, then expands into context and version-specific edge cases. Every sentence adds operational information, and the special empty-verse behavior is placed where it is easy to discover.

  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 one required parameter, with output schema present and safe/idempotent annotations, this description is complete. It specifies what output to expect, spelling, edition, and edge cases. An agent can confidently decide when to use it and know what kind of data will come back.

  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 single parameter is fully documented in the schema, but the description adds practical syntax guidance: "John.3.16", "John.3.16-18", and "John.3" show chapter and range forms, not just a single verse. This is more useful than the schema description alone.

  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?

  "Fetch a verse, a verse range or a whole chapter by OSIS reference" names a specific verb, a clear resource, and the exact input format. It also describes what the result contains (speakers, people, places, themes, cross references), which separates this citation-driven tool from sibling tools like search or find_cross_references.

  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 gives strong context for when to use it: when you have an OSIS reference and want the topical context around a passage, calling it "the main way into the topical side of the knowledge base." It does not explicitly list excluding alternatives, such as 'use search_scripture when you only have words', but the intended use is clear.

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

• search_conceptsA
  4.7/5.0
  Behavior4/5

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

  Annotations already communicate read-only, idempotent, non-destructive behavior. The description adds genuinely useful behavioral context: all terms match with AND logic, adding words narrows results, and this searches metadata rather than full text. It also warns about collection-size skew affecting default queries.

  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?

  Each sentence earns its place: scope, search behavior, practical disambiguation advice, and routing to alternative tools. It is front-loaded with the most important information and stays focused without unnecessary filler.

  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 read-only search tool with full schema coverage, rich annotations, and an output schema, the description covers purpose, behavior, disambiguation, and alternatives. An agent has enough information to select and invoke the tool correctly without inspecting sibling tool schemas.

  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 100% and parameter descriptions already document each field. The description adds meaning beyond the schema by explaining how the query parameter behaves (AND matching), why type is important, and what the type values represent. It does not deeply elaborate on tag or offset semantics, but those are already clear from the 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 a specific verb and scope: search every document in the knowledge base by name, description, tag, path and type, and names the many collections covered. This immediately distinguishes it from general document listing and from searching the text of Scripture.

  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 states exactly when to use this tool versus alternatives: search concepts metadata with this tool, search Scripture text with search_scripture, and fetch a known reference with get_passage. It also gives practical guidance on using the type parameter to avoid ambiguous results.

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

• get_familyA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds essential behavioral context: the corpus has no child-of edge, this tool performs the inversion, ancestor-of edges cannot be composed into a generation tree, and genealogy passages are a separate theme. This goes well beyond the annotations.

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

  Conciseness4/5

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

  The main functionality is front-loaded in the first sentence with examples, and the exclusions/alternatives follow. The later naming-rationale explanation is longer than strictly necessary, but every sentence either routes behavior, gives data-model warnings, or clarifies scope. It is appropriately sized for a complex tool with data-model pitfalls.

  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 tool with complex lineage semantics, the description covers all needed topics: the precise result (parents/children/siblings/spouses), how generations expands the result, the crucial data-model inversion, excluded relation types, and alternative access points. Given the output schema exists and parameter schemas are complete, nothing important is missing.

  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 100%, both parameters have descriptions, so baseline is 3. The description adds a concrete path example, clarifies which parameters affect lineage depth, and states that generations are gathered one generation at a time, which briefly specializes meaning beyond the schema's one-sentence parameter descriptions.

  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 has a specific verb + resource: it returns parents, children, siblings, and spouses for a person, and with generations above 1 a generation-by-generation line of descent. It uses concrete example queries like 'who were Boaz's ancestors' and explicitly distinguishes itself from get_entity, so the agent can tell it 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.

  Usage Guidelines5/5

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

  It explicitly says 'Use this rather than reading relations off get_entity' and explains why parentage is recorded only on the parent's document. It also tells the agent that ancestor-of edges and genealogy passages should be obtained elsewhere (get_entity, themes/genealogy), so both inclusion and exclusion criteria are spelled out.

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