VineVerse — Bible Knowledge Graph

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

Annotations already mark the tool as read-only and idempotent, but the description adds meaningful behavioral nuance not already present: references have no recorded relationship type, and a lower minVotes does not expand results because chapter documents only materialize references at or above 20 votes. This is genuinely useful behavior disclosure.

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

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

The description is compact and front-loaded: the first sentence states what the tool does, the second gives an important data-model caveat, and the final sentence covers a materialization threshold and a corpus pointer. No sentence is wasted.

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

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

Given that an output schema is present and annotations cover safety flags, the description is complete for a 3-parameter read-only tool. It covers the essential edge case around minVotes, explains the no-relationship-type constraint, and points to a full dataset alternative.

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

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

The schema already covers all three parameters with descriptions, so baseline is 3. The description goes beyond schema by explaining the consequence of setting a low minVotes (the 20-vote materialization floor) and by clarifying the ordering guarantee. This adds value for invoking the tool correctly.

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

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

The description states a specific verb and resource: "Cross references for a verse or chapter", with a distinguishing characteristic, "ordered by crowd support". It is clearly not about passages, entities, vocabulary, or other sibling concerns, so an agent can disambiguate it from the listed sibling tools.

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

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

The description provides clear operational context, such as the fact that references carry no relationship type and that lower minVotes will not widen results for chapter documents. It does not explicitly name a sibling tool to use instead or state when-not to use it, but it gives enough context for correct invocation.

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

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

Annotations already mark the tool as read-only and idempotent, so the description does not need to repeat safety information. It adds meaningful behavioral context: nearest-first ordering, distance in kilometres, roughly 1,300 coordinate-bearing places, and a caveat that many identifications are tentative and should be verified via `contested`/`identifications`.

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

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

The description is compact and well-structured: core behavior first, then the two anchor modes, then a reliability caveat. Every sentence carries useful information, and the important sorting/distance semantics are front-loaded.

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

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

For a read-only lookup with rich parameters and an output schema, the description covers the essential context: user intent, both possible anchor types, and data reliability guidance. The defaults for `limit` and `radius` are already in the schema, so the description does not need to repeat them.

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

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

The schema already documents all 5 parameters with 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining the relationship between `place` and `lat`/`lon` modes, and by clarifying that `place` should already exist in the knowledge base while bare coordinates suit modern locations.

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

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

The description states a specific verb and result set: find Biblical places within a radius, ordered nearest first, with distance in kilometres. It distinguishes this tool from search and entity lookups by naming the two anchor modes: an existing place in the knowledge base or a bare latitude/longitude for a modern location.

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

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

The description gives clear context on how to use the tool and when each anchoring method is appropriate, including the special case of a modern location not documented in the knowledge base. It does not explicitly name alternative tools or exclusion conditions, but the guidance is sufficiently actionable for an agent.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by explaining that `generated` in get_stats changes on every restart and reflects the process rather than the data, which helps the agent avoid misinterpreting the values. It could go further by describing the exact shape of the returned log, but the output schema already covers that.

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

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

The entire description is one tight, information-dense sentence. It front-loads the resource, then provides a concrete use case, then a precise contrast with get_stats. Every clause earns its place: no filler, no repetition, and the crucial disambiguation appears before the sentence ends.

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

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

With no parameters, full schema coverage, robust annotations, and an output schema, the description has a narrow job: telling the agent what the result means and when to use it. It explains the purpose, the key field `bundleGenerated`, and the distinction from get_stats' `generated` field. There is no critical missing guidance for someone deciding whether to call this tool or how to interpret its output.

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

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

The tool has zero parameters, so baseline 4 applies. The input schema covers 100% of parameter documentation and there is nothing for the description to add. The description focuses instead on output semantics, which is the appropriate place to provide value.

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

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

The description clearly states that this tool returns the knowledge base's own log file plus the actual data ingest time, and introduces the `bundleGenerated` field by name. It explicitly differentiates from get_stats' `generated` field, which describes a process fact rather than data freshness.

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

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

The description explicitly says when to use this tool: when the agent needs to answer how current the data is or cite a version, use `bundleGenerated`. It also directly contrasts get_stats' `generated` field, providing a clear decision rule between this tool and a sibling alternative.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: the operation is shaped by which argument is provided, and the no-argument variant returns aggregate rankings. It doesn't discuss edge cases like conflicting arguments, but the annotations cover the main safety profile.

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

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

The description is compact and front-loads the purpose before describing the usage modes. Every sentence earns its place, and the routing sentence to the sibling tool is integrated naturally.

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

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

Considering all parameters are optional, the schema is self-documenting, and the output schema exists, the description adequately covers how to invoke the tool and select between modes. It gives enough context for an agent to choose get_connections over find_cross_references.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches parameter meaning beyond the schema: 'book' returns one book's incoming/outgoing rows, and 'osis' returns a chapter's rank/vote weight. This adds real decision guidance for which argument an agent should choose.

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

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

The description clearly identifies the resource as the aggregate shape of the cross-reference corpus, stating specific outputs like totals, hub chapters, and book-to-book pairs. It also explicitly differentiates from find_cross_references, which handles actual references.

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

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

It explains the no-argument mode, the book mode, and the osis mode, and explicitly directs the agent to use find_cross_references when actual references are needed. This gives clear conditions for choosing between sibling tools.

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

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

Read-only, idempotent, and non-destructive are already marked by annotations, but the description adds genuine behavioral depth: relations are stored once on one side only and require relations.inbound, body content is only available via body=true, and collection paths return what the collection holds. These are non-obvious behaviors that materially affect how the agent reads results, going beyond the annotations.

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

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

The description is front-loaded with the core action and then provides a highly scannable, organized list of path examples. The dense examples and behavioral notes earn their place. It is slightly long, and a reader could skim parts, so it does not quite hit a perfect 5.

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

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

For a read-only entity-fetch tool with a rich output schema, the description is complete. It covers accepted path types, disambiguation rules, collection-return behavior, the asymmetrical relation semantics, and the body/backlinks options. The 'search first' pointer covers the main error-prone scenario, leaving no critical gap for an agent invoking the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by mapping accepted path prefixes (places/bethel-1, themes/faith, bible/john/3) beyond the schema examples and explains that collection paths like 'themes' return the collection's holdings rather than a single document. It adds value but mostly confirms what the schema already documents, hence 4.

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

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

The first sentence states a specific operation: 'Fetch any document in the knowledge base by path' — a clear verb, resource, and scope. The extensive enumeration of supported path families (people, places, themes, lexemes, books, chapters, etc.) removes any ambiguity and makes the tool's role distinct from the search-oriented siblings.

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

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

It explicitly tells the agent to 'search first if unsure' about a disambiguated name, which is a direct conditional routing to the search sibling. It also explains when to set body=true because the prose lives nowhere else. However, it does not cover all sibling alternatives or say when NOT to use this versus get_connections or find_cross_references, so a full 5 is not warranted.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, so no contradiction. The description adds crucial behavioral context not visible in the schema: the corpus stores parentage only on the parent's document, so get_family performs a needed inversion. It also discloses the limitation that ancestor-of edges are excluded because they cannot be composed into a generation-by-generation tree. This is exactly the hidden-behavior disclosure an agent needs.

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

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

The description is front-loaded with the core purpose and then gives only behaviorally important details: the inversion gotcha, the excluded edge type, and where to find alternative data. It is a bit long for a tool description, but every sentence adds decision-relevant value for an agent, so the length is earned rather than padded.

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

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

Given the tool has a rich output schema, full parameter coverage, and safety annotations, the description completes the picture by clarifying scope, distinguishing from sibling tools, exposing a critical data-model quirk, and offering fallback slices for excluded data. An agent has enough context to select and invoke this tool correctly without further investigation.

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

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

The input schema covers 100% of parameters, so the baseline is 3. The description adds meaningful semantics for the `generations` parameter by explaining it gathers ancestors and descendants one generation at a time, which clarifies the traversal ordering. The `path` usage is reinforced with example like do people/moses and the genealogy question examples map naturally onto parameters.

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

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

The description names a clear verb and resource (get a person's family and line of descent) and enumerates the specific relationship types returned: parents, children, siblings, spouses, and optionally ancestors/descendants. It explicitly distinguishes itself from get_entity and from genealogy-related indexes, so an agent can accurately differentiate it among siblings.

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

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

The description gives explicit when-to-use guidance: use it for genealogy, lineage, or ancestry questions, with concrete example queries. It also states when not to rely on it, directing the agent to get_entity for the 680 ancestor-of edges and to themes/genealogy for genealogical passages. This is strong alternative routing.

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

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

Annotations already convey that this is read-only, idempotent, and non-destructive, so the description does not need to justify mutation behavior. The description adds valuable behavioral nuance: it states what is included in the response, warns that depth 3 is expensive and capped, and implies a `truncated` response when the limit is hit. It complements the annotations cleanly and contains no contradiction.

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

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

The description is compact and structured well for agents: first the core capability, then the practical filtering examples, then limits, and finally the reference for predicate vocabulary. Every sentence earns its place, and the key purpose is stated upfront without boilerplate.

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

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

Given the output schema and full parameter-level schema descriptions, the tool description covers what hits the remaining gaps: purpose, filtering strategy, depth behavior, caps, and the predicate vocabulary reference. An agent can correctly understand what the tool does, when to use it, and how to construct a useful call without additional external clues.

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

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

Schema description coverage is 100%, so the baseline is high. The description adds useful semantics beyond the schema by showing how `type` supports shaped queries, how `predicate` can narrow to one edge kind, and what "depth" means practically with depth 1 versus depth 3. It does not add unique details for every parameter, but it meaningfully increases the agent's ability to choose effective parameter values.

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

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

Description clearly defines the operation as returning everything within N hops of a document, including edges and predicates, which is concrete and distinct. It goes beyond a mere restatement by describing graph traversal semantics. However, it stops short of explicitly differentiating from sibling tools like get_connections or find_places_near, so agents must infer the uniqueness of this tool.

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

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

The description provides clear usage context: "Useful for asking what a passage, person or theme is connected to without fetching each document." It also shows how `type` can shape questions and points to `get_vocabulary` for predicate meanings. It does not explicitly state when not to use this tool or name alternatives, so it stops short of full usage guidance.

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

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

The description goes beyond the annotations by disclosing meaningful behavior: entries are in English order, lexeme presence is conditional, the Greek lexicon is absent, and some verses are skipped due to Berean edition disagreement. This is exactly the kind of behavioral context an AI agent needs.

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

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

The description is dense but front-loaded and every clause earns its place: the main purpose, the reverse-interlinear ordering, entry fields, and data availability limitations. It is long because the domain is complex, not because it repeats information already in quick access.

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

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

Given the output schema, annotations, and the one documented parameter, the description covers all important edge cases and expectations: what each entry contains, when lexeme is omitted, the lexicon scope, and the five verses with no data. It points to the changelog for those verse names, which is the right mechanism.

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

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

The schema already fully documents the single required parameter, osis, with explicit verse/chapter examples. The description restates 'one verse or whole chapter' but does not add materially new parameter guidance, so it meets the baseline for high schema coverage.

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

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

The description states exactly what the tool does: it returns the Hebrew/Aramaic/Greek original-language words behind an English passage, word by word, as a REVERSE interlinear. This distinguishes it clearly from sibling text access tools like get_passage.

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

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

The description gives clear context for when to call the tool — for a single verse or whole chapter when the original-language form and grammatical details are wanted. It does not explicitly name alternatives or exclusions, but the intended use case is evident.

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

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

Annotations already mark this as read-only and idempotent, and the description adds meaningful behavioral context: the exact text source (Berean Standard Bible), the intentional presence of empty verses for manuscript reasons, and the rich contextual payload returned with verses/ranges. This goes beyond what annotations alone convey.

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

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

The description is well-organized in three short paragraphs: what is fetched, what comes back with it, and important translation-specific behavior. Every sentence contributes useful information, with examples front-loaded for immediate comprehension.

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

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

For a single-parameter read-only tool with an output schema, this description is complete: it defines accepted reference forms, explains the enrichment context returned, notes the Bible translation used, and discloses the empty-verse edge case. No important call-correctness fact omitted.

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

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

Schema description coverage is 100% and already provides representative OSIS refs for verse, range, and chapter. The description mostly restates the same examples in prose, so it adds limited new meaning beyond the schema.

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

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

The description names a specific verb ('Fetch') with a specific resource ('a verse, a verse range or a whole chapter by OSIS reference') and gives concrete reference syntax. This clearly differentiates the tool from search-oriented siblings and makes its function immediately obvious.

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

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

It describes when to use the tool for exact OSIS-based passage retrieval and explains that the returned context is 'the main way into the topical side of the knowledge base from a passage.' It does not explicitly contrast with sibling tools like search_scripture, 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.

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

Annotations already establish this as read-only, idempotent, and non-destructive. The description adds useful context about the tool's role as an orientation map and enumerates the kind of content returned, which is relevant behavioral context for an agent deciding whether to call this before other tools.

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

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

The description is compact, front-loaded with the main identity, and every phrase earns its place. Ending with the 'map to every other tool' framing is both useful and memorable without adding unnecessary length.

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

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

For a no-parameter, read-only overview tool with annotations and an output schema already available, the description is complete. It tells the agent what the tool surfaces, why it matters, and when to call it first.

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

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

The tool has zero parameters, so there is no parameter surface for the description to clarify. The schema confirms this with an empty properties object, and the description does not need to compensate; the baseline of 4 applies.

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

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

The description clearly identifies the tool as a catalogue/overview of the entire knowledge base, including document counts, folders, example paths, tags, and licences. It distinguishes itself from content-specific siblings by framing itself as 'the map to every other tool.' The title reinforces the purpose, and the description goes beyond a mere label.

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

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

The description explicitly says to call this tool first when the agent does not know what the knowledge base holds. It gives clear contextual guidance for the main use case, though it does not name specific alternatives or state when it should be avoided.

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

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

Beyond the annotations, the description adds behavioral detail: tags are aggregated across collections, counts include documents carrying that tag, and results are most-common-first. These are behavioral traits that structured hints do not express.

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

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

Two sentences, front-loaded with the core result and ordering, followed by illustrative examples and a concrete downstream use. Every sentence earns its place without redundancy.

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

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

Given the output schema, annotations, and fully described parameters, the description is largely complete. The one gap is lacking an explicit tie-breaker vs the get_vocabulary sibling, which might matter for an agent choosing between them.

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

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

Schema coverage is 100%, and both limit and offset have clear descriptions. The description adds minimal extra meaning, though mentioning the most-common-first order reinforces how offset will behave. The parameter semantics are adequately documented without heavy dependency on the description.

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

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

The description clearly states that it returns every tag in the bundle along with its document count, sorted most-common-first. It gives concrete examples and distinguishes tags from generic collection terms. However, it does not explicitly differentiate from the sibling get_vocabulary, which might cause some ambiguity.

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

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

It implies usage by noting that any tag returned can be passed to search or list_documents for filtering. This gives useful downstream context but does not state when to choose get_tags over alternatives like get_vocabulary, nor does it mention exclusions or when not to use it.

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

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

The annotations mark the tool as read-only and idempotent, and the description goes further by revealing a non-obvious behavioral trait: relations are stored one-directionally, so raw relation arrays always read outward from the fetched document. It also emphasizes the vocabulary is a closed set, which is contextual data behavior beyond the structured fields.

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

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

Every sentence in the description provides necessary information: the predicate vocabulary, the canon table, the directionality caveat, and the usage pointer. It is front-loaded with the most critical content and contains no repetition or filler.

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

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

Given that an output schema exists and annotations cover the read-only safety profile, the description supplies all needed behavioral context: what the returned data contains, how predicates are organized, a concrete example (Song), and a crucial directionality warning. An agent can decide when and how to invoke it correctly.

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

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

The input schema has zero parameters, so the baseline of 4 applies. The description correctly adds no unnecessary parameter details because there are none to clarify.

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

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

The description uses a specific verb ('returns') and names a concrete resource: the closed set of graph predicates and the canon table, including their meanings, inverses, and usage counts. This clearly differentiates it from all sibling tools, which focus on references, entities, connections, passages, or searches.

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

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

It communicates when to use the tool: 'Read this before interpreting a predicate' and before building a reference against the canon table (e.g., finding the OSIS slug 'Song'). It does not explicitly name a sibling alternative, but given that no sibling covers vocabulary/canon data, this is a clear enough use case.

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

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

Annotations already communicate read-only, idempotent, non-destructive behavior. The description goes well beyond this by stating default sort orders (chronological for epochs/events, alphabetical otherwise), how to page using offset and total, and that the response reports whether more items remain. These behaviors meaningfully guide an agent without repeating the annotations.

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

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

The description is well-organized: purpose and usage are front-loaded, the collection inventory is compactly listed, and a short paragraph covers ordering and paging. Every section earns its place and supports either selecting the tool or invoking it correctly.

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

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

For a read-only, 6-parameter listing tool with an output schema present and no required parameters, the description covers what collections exist, how ordering works, how pagination works, and how folder scoping behaves. It also points to complementary tools like get_tags for the tag vocabulary. No important operational gap remains.

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

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

The input schema already covers 100% of parameters, so the baseline is 3, but the description adds substantial meaning: it explains the type collection names including folder-path aliases, identifies the bible/ folder ambiguity between Books and Chapters, clarifies that folder is the only path-based scoper, and explains default ordering per collection. This goes well beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Browse or page through any collection in the knowledge base.' It then gives concrete example questions ('what events are recorded', 'list the epochs in order') and contrasts the tool with lookup tools ('rather than to look one thing up'), making its purpose and boundaries clear.

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

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

The description explicitly states when to use this tool: 'when you want to know WHAT EXISTS rather than to look one thing up.' It also provides detailed collection names, ordering defaults, foofolder scoping, and says how to page, so an agent knows exactly when to choose this over a lookup or search tool.

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

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

Annotations already declare read-only idempotent, and non-destructive behavior, and the description goes beyond that by disclosing AND-matching, metadata-only scope, and the practical implication of uneven collection sizes. It doesn't disclose result ordering or default sorting behavior, but the output schema and annotations cover most of the remaining context, so the summary description is still a high-4.

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

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

Every sentence has a clear job: the first scopes the search, the second explains matching semantics and the `type` workaround, and the third distinguishes the tool from sibling tools. It avoids filler and is appropriately front-loaded, prioritizing purpose and just enough behavioral nuance.

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

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

Given a complete input schema, a zodiac annotation set that already marks the operation read-only, idempotent, and non-destructive, plus an existing output schema, the description needs only to clarify scope and routing. It does this thoroughly and even anticipates a real ambiguity by saying 'for searching Scripture text use search_scripture...' Nothing important is 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.

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

The input schema already describes all five parameters with 100% coverage, so this is a high baseline. The description adds meaningful semantics above the schema: `query` terms are AND-combined, adding terms narrows the result, and `type` matters because ~3,000 people and ~3,000 themes can produce ambiguous hits. Limit/offset rely on the schema, but the core query and type parameters are enriched.

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

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

Opens with a clear verb and resource: 'Search every document in the knowledge base' and immediately enumerates searchable fields and covered collections (people, places, themes, lexemes, etc.). The later sentence 'This searches concept METADATA' removes ambiguity between this tool and Scripture-text search, and the description names sibling tools for contrast. Purpose is unmistakable.

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

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

The description gives concrete usage rules: all terms must match (AND), adding words narrows results, and `type` should be used to avoid a large collection dominating an unfiltered search. It also explicitly says when the user should use search_scripture and get_passage instead, which qualifies as strong when/when-not guidance.

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

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

The description discloses behavior well beyond the annotations: all words must appear in the same verse, double quotes make phrases, and results are ranked by how much of the verse matches the query. These details give an agent a concrete model of how the search works and what to expect from the results.

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

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

The description is five sentences, each carrying necessary information: the core action, the typical use case, query constraints, ranking, and a filtering tip. It is front-loaded with the main action and contains no redundant or promotional language.

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

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

Given an output schema exists and all parameters are documented, the description covers everything needed to use the tool effectively: it defines search scope, query syntax, ranking logic, and performance-oriented tuning. No important behavioral aspect of the search operation is left unexplained.

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

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

The schema already describes every parameter, providing a baseline of 3. The description adds value for query semantics by specifying same-verse requirement, phrase adjacency, and ranking behavior, and it recommends using book/testament to limit unwanted results. It does not add meaning for limit or offset, but those are already clearly documented in the schema.

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

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

The description opens with 'Full-text search across all 31,102 verses of the Berean Standard Bible', giving a specific verb, resource, and scope. The second sentence explains a clear use case (a passage you half-remember but cannot cite) and distinguishes it from citation-based retrieval tools like get_passage.

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

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

The phrase 'This is how you find a passage you can half-remember but cannot cite' clearly sets expectations for when to use this tool, and the guidance to restrict with book or testament addresses common-search scenarios. However, it never names alternatives or states explicit when-not-to-use conditions, leaving some sibling differentiation to inference.

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