bible-mcp

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't mention whether versions differ in language/style, what 'side by side' means in terms of formatting/output, or whether the tool performs translation-level comparison or just text display. The description is minimal on behavior beyond the basic display action.

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?

One sentence, zero waste, front-loaded with the verb and resource. Every word earns its place. This is appropriately concise given the tool's single parameter and straightforward purpose.

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

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

The tool has one simple parameter and an output schema exists, so basic completeness is achieved. However, with no annotations and no param-format documentation, the description leaves some gaps around reference format expectations and range limits. The output schema helps, but the description could clarify the 'short range' boundary.

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

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

Schema description coverage is 0% and there's only one parameter (reference). The description mentions 'verse or short range' which gives some hint that reference accepts a passage specifier, but it doesn't clarify the expected format (e.g., 'John 3:16', 'John 3:16-18', book abbreviations). The description adds a bit of context but doesn't fully compensate for the zero 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 clearly states the tool shows a verse or short range in two specific translations (BSB and WEB) side by side, which is a specific verb+resource combination. It's distinct from siblings like get_passage (single version) and get_interlinear (word-by-word analysis), though it doesn't explicitly name those alternatives.

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

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

The description implies use for cross-version comparison but doesn't provide explicit when-to-use or when-not-to-use guidance. The 'short range' qualifier hints at a limit but doesn't state what counts as short, leaving the agent to guess the boundary between this and other 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. Since this is a read-only informational tool with zero parameters, the risk surface is low. The description discloses the scope of information (documents, layers, licenses, counts). However, it does not disclose the return format structure or whether counts follow any particular convention, though an output schema exists to cover this.

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

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

The description is a single, efficient sentence that names the tool's purpose and enumerates its output categories. Zero wasted words, front-loaded with the key phrase 'What's in the corpus'. A question format is used effectively for a quick-overview tool.

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

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

This is a simple parameterless informational tool with an output schema that documents return values. The description adequately conveys the purpose and scope. Given the low complexity (no params, no nested objects) and the output schema covering return structure, the description is reasonably complete. It could optionally note whether results depend on authentication/license access, but that's a minor gap for a corpus-overview tool.

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

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

The tool has 0 parameters, so there are no parameter semantics to clarify. Per the rubric, 0 params = baseline 4. The description appropriately focuses on what the tool returns rather than inputs, which is the correct emphasis for a parameterless tool.

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 'What's in the corpus: documents, layers, licenses, and counts' clearly states the tool reports corpus contents (documents, layers, licenses, counts). It uses a specific noun phrase and enumerates the specific categories of information returned, distinguishing it from sibling tools that operate on passages, entities, or individual works.

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

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

The description implies the tool is for getting an overview of corpus contents (a 'what's in the corpus' overview tool), which is clear context for when to use it. However, it does not explicitly state when NOT to use it or name alternatives—e.g., if you need a specific document's content, use read_work. The context is implied rather than explicit.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It indicates a read-only listing operation implicitly, but doesn't disclose what happens with invalid references, how many entities might be returned, or whether entities are deduplicated across the passage. The output schema exists which mitigates some unknowns, but the description doesn't add much beyond the safe-read implication.

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

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

The description is a single sentence with an inline example, which is efficient and front-loaded. Every word earns its place. It could arguably be scored 5, but the example could have been structured more clearly to demonstrate format flexibility.

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 a single parameter, a helpful example, and an output schema present, the description covers the core use case adequately. However, since no annotations exist and schema parameter description coverage is 0%, the description could do more to clarify what 'entities' means (people, places, events are named, which is helpful) and any limitations on reference format. It's a minimum-viable description for a single-param 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 0%, meaning the schema provides no description of the 'reference' parameter. The description's example ('Genesis 14' or 'John 3:16') implies the format for verse/chapter references, which adds value beyond the bare schema. However, it doesn't specify edge cases like ranges ('Genesis 1-3') or combined references, leaving ambiguity. The single example format helps but is limited.

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

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

The description clearly states the verb 'List' with a specific resource ('the people, places, and events linked to a verse or chapter'). It provides a concrete example ('Genesis 14' or 'John 3:16') that clarifies the expected input. This distinguishes it from siblings like get_passage (verse text) and get_cross_references, though it doesn't explicitly name those distinctions.

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 indicates the tool is for listing entities within a passage, which implies when to use it (when you want entities associated with a reference). However, it provides no explicit exclusions or comparisons to alternatives like get_entity (which presumably returns a single entity's details) or semantic_search. The context is implied rather than explicit.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The description indicates this performs semantic similarity across multiple corpus layers (a potentially expensive operation) but doesn't disclose rate limits, cost characteristics, or expectations around semantic search quality. It also doesn't describe return format shape. For a computation-heavy tool with zero annotations, more transparency would be valuable.

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

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

Three sentences with zero waste. The purpose is stated upfront, examples are inlined efficiently, and every sentence earns its place. Well-structured and front-loaded.

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

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

There is an output schema present, which reduces the burden of explaining return values. The tool has only 2 params (1 required), so complexity is moderate. The description covers reference format via examples and scopes the corpus clearly. Minor gaps: top_k is undocumented and 'parallel-finding' isn't elaborated, but overall it's reasonably complete for a moderately simple 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 0%, so the description must compensate. The description provides a helpful example of valid 'reference' format ('Philippians 2:7', 'JULIAN.27.2'), which adds meaning beyond the bare schema label. However, it says nothing about 'top_k' semantics beyond its numeric nature, and with 0% coverage the baseline 3 is warranted but not exceeded.

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

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

The description clearly states it finds passages semantically similar to a given ref, with a concrete verb ('Find') and resource (passages across scripture, Apocrypha, classics). It provides examples of valid references ('Philippians 2:7', 'JULIAN.27.2'). However, it doesn't explicitly distinguish from sibling tool 'semantic_search', which could be confused with this one since both involve semantic matching.

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

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

The description implies usage ('Powers parallel-finding across corpus layers') and gives example input formats, but provides no explicit when-to-use vs alternatives. Notably, 'semantic_search' is a sibling that likely overlaps in purpose, yet no guidance distinguishes when to use find_similar vs semantic_search. The examples of reference format are helpful context though.

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?

Despite no annotations, the description is exceptionally transparent: it discloses known recall gaps, states that empty results do NOT mean the verse is uncited, and reveals the extraction source (translators' footnotes, tier 1). It even explains that verbatim quotations are regularly missed by the footnote index. This fully carries the behavioral-disclosure burden in the absence of 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?

Tightly written with zero waste — the purpose statement, complementary-tool contrast, and coverage caveat are each one focused sentence. The coverage note is clearly delimited and earns its place given its operational importance for the agent.

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 2-parameter lookup with an output schema present, the description covers purpose, interpretation of results, limitations, and alternative strategies. The coverage caveat is critical context that directly affects how an agent should interpret tool output, and it is addressed head-on. Very complete.

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

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

Schema description coverage is 0%, so the description must carry the parameter-meaning load. It provides a concrete example of the reference format ('Ephesians 5:21') and explains what the reference means in this context. The limit parameter is not explicitly described, but the high-clarity usage context partially compensates. Slightly above the baseline 3 given the useful reference-format example.

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

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

States a specific verb+resource ('Where a Bible verse is cited by name in the patristic corpus, extracted from the translators' own footnotes'), gives a concrete example (reference='Ephesians 5:21'), and explicitly distinguishes from the sibling get_cross_references. 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?

Explicitly contrasts with get_cross_references ('links scripture to scripture; this links patristic text to scripture') and offers a clear alternative — full-text search — when footnote extraction returns empty. Also warns about recall gaps and tells the agent when to fall back to search. Very 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?

No annotations are provided, so the description carries the burden. It discloses that results are ranked by community votes and includes target text, which is useful. However, it doesn't describe behaviors like whether the ranking is ascending/descending, rate limits, or data freshness. It's read-only in nature but doesn't explicitly state so.

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

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

The description is two sentences with a concrete example. It packs source, ranking, and output content into the first sentence. The example is well-placed. Minor waste: the example could be considered redundant with the reference parameter, but it adds concrete grounding. No excess text.

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

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

The tool has an output schema, so return-value documentation is covered structurally. With 2 parameters and one explained via example, the description covers the core use case. Given the tool's moderate complexity, the description is reasonably complete, though the limit parameter semantics could be more explicit.

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

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

Schema coverage is 0%, so the description must compensate. It explains the 'reference' parameter through the example 'Romans 5:12' and the target text behavior. However, the 'limit' parameter (default 20) is entirely unexplained in the description, leaving the agent unsure of its meaning without schema explanation.

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 verb+resource: 'Cross-references for a verse (OpenBible.info, ranked by community votes), with the target text included.' It names the data source, ranking mechanism, and includes an example query. This distinguishes it from siblings like get_citations, find_similar, and word_study.

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

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

The description provides an example usage (reference='Romans 5:12') which implies the query format, but does not explicitly state when to use this tool versus alternatives like get_citations or find_similar. Usage context is implied but not explicit.

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

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

With no annotations provided, the description carries the burden of disclosure. It does mention the return content (details and where they appear), which is helpful. However, it doesn't disclose what happens with ambiguous names, whether partial matches are supported, case sensitivity, or whether it returns one result or multiple. It's a read tool so no mutation concerns, but behavioral detail is thin.

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 concise sentences with zero waste. The first establishes purpose and output, the second documents the optional parameter's allowed values. Every sentence earns its place.

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

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

The tool has an output schema (which explains return value structure), reducing the burden on the description for output details. With 2 params (only 1 required) and modest complexity, the description covers purpose and parameter options adequately. However, given 0% schema coverage and no annotations, it could do more with edge cases like ambiguity handling, given the sibling ecosystem has several search/citation tools that could overlap.

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

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

Schema coverage is 0%, so the description must compensate. It does explain what entity_type means with enumerated allowed values (person | place | event | people_group), which adds value. However, it provides no detail on what the name parameter expects (exact match? partial? canonical form?) or how entity_type interacts with name filtering beyond being optional.

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

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

The description clearly states the verb (Look up) and resource (biblical person, place, event, or people group via a Theographic knowledge graph), and mentions it returns details and appearances. It's clear but doesn't explicitly distinguish from siblings like get_citations or get_cross_references, though the domain (biblical entities) is somewhat distinct.

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

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

The description notes entity_type is optional with allowed values, providing light guidance. However, there's no explicit when-to-use guidance, no mention of how this differs from correlated tools like semantic_search, word_study, or search, and no exclusions or alternative tool pointers.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It lists the output fields (surface form, lemma, Strong's, gloss, morphology) which is helpful, but doesn't disclose limits on range length, whether original language availability varies by work (e.g., modern works lacking Hebrew/Greek), failure behavior for invalid references, or output volume/size for longer ranges.

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?

One dense, efficient sentence with examples and a field list. No wasted words 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?

A single-param tool with simple schema, and an output schema exists (so return format is partially covered). The description covers the core semantics adequately for typical use, but gaps in range limits, language-availability caveats, and reference format conventions make it incomplete for edge cases.

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

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

Schema description coverage is 0%, so the schema provides no documentation of 'reference'. The description adds meaning via examples (book chapter:verse and range format). However, it doesn't specify the exact expected syntax nuances (e.g., spacing, zero-padding, verse range separators like '-' vs '–'), abbreviations, or case sensitivity, leaving part of the burden unmet.

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

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

The description clearly states the tool provides word-by-word original language data (surface form, lemma, Strong's, gloss, morphology) for a verse or short range, with concrete examples. This distinguishes it from siblings like get_passage (plain text) and word_study (deeper lexical analysis), though it doesn't explicitly name the alternative.

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 examples ('John 1:1', 'Genesis 1:1-3') imply the reference format and that short ranges are supported. However, there's no explicit when-to-use vs alternatives guidance, no exclusion criteria (e.g., don't use for long passages, use get_passage for plain text), and no format spec for the reference string beyond examples.

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

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

No annotations provided, so the description carries the full burden of behavioral disclosure. It does note the Apocrypha version constraint, which is useful, and lists available versions (BSB, WEB). However, it doesn't disclose the output format/structure, what happens for invalid references, or whether returned text includes section headings or verse numbers. With zero annotations, more behavioral context is expected.

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?

Extremely concise and efficient. Two sentences cover purpose, examples, a constraint, and supported versions. No wasted words, all information is relevant and immediately useful.

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

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

This is a relatively simple tool (2 params, 1 required), and the description covers purpose, examples, version options, and an edge-case constraint. An output schema exists, so return format doesn't need documenting. Given the low complexity, this description is reasonably complete, though it could note error behavior for malformed 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 description coverage is 0%, so the description must compensate for parameter documentation. It explains the 'reference' parameter well with examples ('John 3:16', ranges, books) and the 'version' parameter with supported values (BSB, WEB). However, it doesn't fully compensate — e.g., it doesn't explain what happens with ambiguous references, book abbreviations, or chapter-only queries beyond one example ('Genesis 1').

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

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

The description clearly states the tool gets Bible text for a reference, with specific verb+resource ('Get Bible text') and concrete examples. It includes reference format examples and distinguishes from siblings by focusing on passage retrieval, which contrasts with tools like get_cross_references, get_entity, or word_study.

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 when to use it (to fetch Bible text by reference) with concrete format examples. It also includes a usage constraint for Apocrypha (requires version='WEB'). It doesn't explicitly exclude cases that belong to siblings (like word_study or get_cross_references), but the purpose is clear enough that distinctions are implied.

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

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

No annotations are provided, so the description carries the full burden. It explains the chapter semantics mapping and notes that it reads by paragraph range, but doesn't disclose behavior like whether reads are cost-free, pagination limits, or what happens with out-of-range paragraph numbers. Given the field scope covered (setting expectations for chapter vs paragraph semantics), a 4 is generous but reasonable.

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

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

The description is compact—two sentences plus a work listing. The work enumeration takes space but is genuinely necessary since there's no enum in the schema. The usage directive is folded efficiently into the second sentence. Could be slightly more concise in the work list but it serves a real purpose.

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

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

With an output schema present, the return format isn't the description's job. Given 4 params at 0% schema coverage and no annotations, the description covers the most critical ambiguity (work enumeration and chapter semantics) and points to search and corpus_info as discovery aids. The start/end paragraph range semantics remain slightly under-specified, keeping it at 4.

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

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

Schema description coverage is 0%, so the description must compensate for all 4 params (work, chapter, start, end). The description clarifies work (lists valid values and how to discover them) and chapter (mapping to book chapters). However, start and end paragraph semantics are implied but not fully spelled out (e.g., whether end is exclusive), so it falls short of 5.

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

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

The description clearly states the verb+resource: 'Read a prose work from the corpus by paragraph range.' It names all 8 available works, distinguishing it from the 11 sibling tools (search, get_passage, etc.) which serve different purposes (searching, comparing, citation retrieval).

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 guides when to use this tool vs alternatives: 'use search(version=<WORK>) to find passages first, or corpus_info() for the full list.' It also clarifies the chapter semantics ('Chapters = books/chapters of the work'), directly addressing a likely source of confusion and providing actionable next steps.

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

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

No annotations provided, so the description carries full burden — and it delivers richly. It discloses a nontrivial behavioral quirk (porter stemming conflating 'desert' with 'deserted'/'deserts') and advises mitigation (quote exact phrases, add AND-terms). This is exactly the kind of behavioral transparency that prevents surprising 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?

Well-structured and front-loaded with the core purpose. The example block is efficient and the stemming caveat is valuable, not filler. Slightly verbose with the parenthetical explanation of stemming, but every sentence earns its place. Could arguably be tightened but is appropriately sized for the complexity it conveys.

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 query language complexity (stemming, boolean operators, phrases), the description does well explaining syntax and behavioral nuances. An output schema exists (covers return values). The main gaps are undocumented parameters (limit, version) and no explicit mention of result ranking semantics, but coverage is strong overall for a search 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 0%, so no parameter documentation exists in the schema. The description compensates by explaining query syntax (phrases, AND/OR/NOT) and the book filter example ('Psalms'). However, limit, version, and the return/output behavior aren't addressed in the description beyond the schema's titles and defaults.

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?

Clear specific verb+resource: 'Full-text search (stemmed, ranked)'. Demonstrates query syntax with examples and distinguishes from sibling 'semantic_search' by implying this is lexical/keyword-based rather than semantic. Purpose is immediately obvious and differentiated.

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

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

Provides concrete usage context: explains phrase syntax (quotes), boolean operators (AND/OR/NOT), optional filters (book, version), with worked examples. Lacks explicit 'when not to use' guidance versus semantic_search or word_study, but the examples and capabilities strongly imply the appropriate 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?

With no annotations provided, the description carries the full burden. It explains the embedding mechanism, optional hybrid fusion, and how the tool differs from keyword matching. However, it doesn't disclose return format details, pagination, or performance implications of hybrid mode despite an output schema existing. The behavioral description is adequate for what it covers but omits some relevant traits like result ordering or limits.

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 information-dense in three sentences. It includes examples, the full scope, and optional parameter meanings. Slightly dense single-flow paragraph could benefit from bullet separation, but each sentence earns its place with no waste.

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

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

Given the tool's moderate complexity (4 params, output schema present, no nested objects), the description covers the core search semantics, scope, examples, and two of four parameters. The presence of an output schema covers return-shape concerns. The main gap is the undocumented 'top_k' parameter and no guidance on query formulation best practices. Reasonably complete for the complexity level.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain 'kind' ('verse | window | paragraph') and 'hybrid' (fused with keyword search, recommended). However, 'query' and 'top_k' are not described — top_k's default of 12 and its meaning as a result-count limit are left entirely to the schema. The description partially compensates for the zero schema coverage but misses two of four parameters.

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

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

The description clearly states 'Meaning-based search across the whole corpus — scripture AND prose works — using embeddings'. It uses a specific verb (search), identifies the resources (whole corpus), and explains the distinctive capability (finds passages about a theme even with no shared words). This distinguishes it well from siblings like 'search' (keyword-based) and 'find_similar'.

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 specifies the scope (whole corpus), the optional hybrid mode ('optionally fused with keyword search', 'recommended'), and gives concrete examples ('divine self-emptying', 'the soul's dark night'). While it doesn't explicitly state when NOT to use it or name alternatives, the contrast with keyword search is implicit. It clearly conveys when semantic search is appropriate but lacks an explicit exclusion of alternative tools.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses important nuances: gloss-keyed queries match substrings and 'may conflate lemmas', homographs are split by letter-suffixed variants, and the output lists every variant lemma found. This exceeds a terse annotation-equivalent disclosure, though it does not cover edge cases like empty results or pagination behavior.

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 with the core purpose in the first sentence, then elaborates on query formats and caveats. It's slightly long with a large NOTE block, but every sentence adds meaningful information about homographs, gloss conflation, and language codes. Minor redundancy in the Strong's examples but no wasted 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?

A three-parameter tool with an output schema and no annotations, the description covers the query parameter exhaustively and the language options. The limit parameter and result-shaping behavior are left undocumented, and the breadth of output fields (counts, gloss range, distribution) is stated without detail on sample verse formatting. Slightly incomplete but strong for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the query parameter thoroughly (supported formats, zero-padding optional, notation examples). However, it does not describe the limit parameter's semantics or default behavior beyond its schema default, and the language parameter is only mentioned as an optional list of codes without clarifying which applies to which query type.

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 ('query') tied to a distinct resource (original-language word study across the whole Bible), and clearly enumerates query types (Strong's number, lemma, English gloss) and return fields (counts, gloss range, book distribution, sample verses). It also distinguishes itself from siblings like semantic_search and search by framing itself as a lexical/word-level study tool rather than a passage or semantic 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 gives explicit guidance on when to use it (word study) and includes concrete exclusions: exact-count queries should prefer Strong's or lemma over gloss-keyed queries, and homograph handling via lettered variants. It also documents the optional language parameter with its valid values (grc | hbo | arc), providing actionable alternatives for getting precise results.

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