TrulyRandomVerse

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorldHint false), yet the description still adds substantial behavioral context: the KJV default edition, that non-redistributable editions are refused outright, and that book/chapter/verse always use KJV numbering so editions with divergent chapter numbering (Ukrainian, Douay-Rheims, Geneva, Swedish, Serbian) may map to a neighbouring verse. It also imposes a hard epistemic rule ("Never write about a translation that was not returned by a tool result this turn"), which is behavioral guidance no annotation could carry.

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?

Front-loaded with purpose and the key exclusion, then layered with increasingly specific rules — a sound structure for a tool with this many invocation constraints. It runs long and the "Outside trulyrandomverse.com/ai the default edition is the KJV" framing is deployment-specific clutter, but nearly every sentence carries operational weight.

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 output schema, the description must carry behavior, defaults, refusal modes and numbering caveats, and it does all of that for a 5-parameter tool. The remaining gap is the dangling `lang` reference, which leaves the agent unsure how to actually request a non-English edition; the missing return-shape detail (verse references per edition) is minor.

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 40%, so the description has to compensate, and it largely does: it explains the 2-5 entry constraint on versions, the KJV-numbering contract for book/chapter/verse, and how to reach non-English editions. The major flaw is that it instructs the caller to "pass `lang` for another" edition, but no `lang` parameter exists in the schema — a caller following that instruction will fail, and the actual mechanism (non-English codes inside `versions`) is only revealed by the schema's own array 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?

States a specific verb+resource ("Compare a verse (or short passage) across multiple Bible translations side-by-side") and explicitly names the sibling it is not: "do NOT call this just to fetch a single version (use get_verse_text for that)." An agent can distinguish this from get_verse_text, keyword_search, and the commentary tools without opening any schema.

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?

Gives concrete user phrasings that select the tool ("how does the ASV/BSB say…", "compare KJV and YLT on…"), an explicit exclusion with a named alternative for single-version fetches, a 2-5 version operating range, and a mandatory batching protocol when more than 5 versions are requested. That is as close to exhaustive when/when-not/alternatives guidance as a description gets.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add scope and output context — which it does well: it limits coverage to the 66-book Protestant canon and discloses that the returned `url` is the study page to link. It stops short of stating granularity or size of the payload, but the content enumeration largely compensates.

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 long content list is dense but each clause maps to a distinct payload field, and the imperative routing instruction follows immediately. The single-block paragraph is slightly run-on and could be split into content / usage / output sentences for faster scanning, but nothing is padding.

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 no output schema, so the description carries the full burden of describing returns — and it does so field by field, plus scope limits and how to use the returned URL. An agent has everything needed to decide to call it and to interpret the result.

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 the single `book` parameter already carries an example-bearing description, so the baseline is 3. The description adds only a boundary constraint ('the 66 books of the Protestant canon'), which marginally narrows accepted values but gives no format guidance beyond what the schema supplies.

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

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

The opening states a specific verb and resource ('A whole book of the Bible at a glance') and then enumerates exactly what the tool returns: authorship with patristic evidence, structure, key verse, Strong's-linked words, themes, Christological pointers, cross-links, Fathers' commentary, people and places. That is enough to distinguish it from get_verse_text, get_strongs_detail, and get_commentary_section without opening any schema.

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 gives an explicit sequencing rule — 'CALL THIS FIRST for a question about a whole book' — and names the downstream alternatives ('then go deeper with the verse and word tools'). It also enumerates the qualifying question types (authorship, date, audience, structure, theme, how to read), so the routing decision is unambiguous.

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 only cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavior beyond them: excerpts are marked and capped at ~4,000 characters, duplicate texts of the same writer collapse into also_under, oversized ranges return mode: range_too_large at >200K chars, and results are interleaved by writer and century so limit does not starve variety. The writer_note caveat about Philo, Josephus, and cross-reference entries is a valuable authenticity warning no annotation conveys.

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?

Dense but front-loaded: identification first, then return shape, then the verse/verse_end mechanics, then limit behavior, then the failure mode and steering guidance. Every sentence carries operational information — there is no filler or restatement of the title.

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 no output schema, so the description carries the return contract itself and does so thoroughly: father name, year AD, verbatim text, excerpt/also_under markers, total, quotes_by_verse, and the range_too_large mode. Combined with its coverage of the range-sweep parameter interaction, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is only 40% (limit and verse_end documented, book/chapter/verse bare), but the description compensates well: it explains that verse alone targets a single verse while verse_end must be passed ALSO to sweep a range, and it describes how limit interacts with round-robin selection and total/quotes_by_verse. The book/chapter/verse parameters remain self-evident rather than explained, keeping this below a 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?

Opens with a specific verb and resource — 'Fetch quotes from the early church fathers ... on a verse or verse range' — and names the representative writers. It also positions itself against the sibling search_fathers by explaining that search_fathers with a quote_id returns the full text, so an agent can separate the two without inspecting schemas.

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

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

Explicit invocation rule at the end ('Call it when the question concerns a passage's meaning, theology, or historical interpretation'), plus concrete exclusions and escalation paths: use verse alone vs. verse_end for a sweep, fall back to search_fathers for a full quote, and on range_too_large 'ASK THE USER which passage to focus on rather than calling repeatedly.' It even warns against declaring a verse empty before checking quotes_by_verse.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context that annotations cannot convey — that this is one of three complementary content sources whose output is intentionally partial. It does not say what a missing/empty section looks like, which keeps it below a 5.

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

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

Three short sentences with the core action front-loaded and the section list immediately after. The final sentence slightly restates the preceding one ('None is sufficient alone' follows the pairing advice), which is mild redundancy rather than noise.

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

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

For a four-required-parameter lookup with no output schema, the description establishes the content source and cross-tool relationship but says nothing about return shape, empty/missing sections, or why chapter and verse take no descriptive guidance. Adequate to select the tool, thin on what to expect from a call.

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 only 25% — only 'book' is documented, while chapter and verse are bare integers with no format, range, or validation guidance. The description repeats the section enum verbatim without explaining what any section contains, so it does not compensate for the coverage gap.

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 and resource ('Fetch a section of the curated in-house commentary for a verse') and enumerates the seven section values, so the agent knows exactly what granularity of content is returned. It also explicitly positions itself against siblings by naming get_matthew_henry and get_church_fathers.

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 explicit when-to-use routing: it names the two peer commentary tools to pair with and warns that none is sufficient alone. The exclusion ('do not treat this as "the" source') tells the agent precisely what not to do with the result.

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, non-destructive, closed-world behavior, so the description's job is to add operational context — and it does: results are vote-ranked with a `votes` field, `total` gives the full count, verse text is embedded, and localized editions can degrade to `note: "fallback: english"`. It also discloses the licensing refusal case and the KJV-numbering invariant with specific caveats for Ukrainian, Douay-Rheims, Geneva, Swedish and Serbian editions. Minor gap: pagination/truncation interaction between `total`, `limit` and the ranked list is not spelled out.

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?

Front-loaded with purpose and the sibling alternative in the first two sentences, then moving to return shape and then locale caveats in descending priority. It is dense but nearly every sentence carries unique operational information; only the edition-numbering aside is arguably longer than the decision it supports.

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 output schema, the description carries the return-shape burden and discharges it (referenced verses plus text, `votes` per reference, `total` count, fallback note). For a 5-parameter, 3-required tool the only material omission is the accepted format for `book` and how `limit` interacts with the vote ranking.

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 only 40% (book, chapter and verse have no descriptions), so the description must compensate, and it substantially does: it pins down that book/chapter/verse are always KJV numbering and explains the `lang` default (conversation language, KJV outside trulyrandomverse.com/ai) and the fallback note. It leaves the `book` string format (e.g. 'John' vs 'JHN') unspecified, which is a real ambiguity given a bare string parameter.

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

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

States a specific verb and resource ('Get cross-references for a verse') and immediately characterizes the data source (OpenBible.info, vote-ranked, union of links under either verse). It also names the sibling it is not — get_strongs_occurrences — with the distinguishing criterion (thematic/teaching links vs. shared Hebrew/Greek lemma), so an agent can pick between them without opening a schema.

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

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

Explicit routing guidance: use get_strongs_occurrences (with `followed_by`) when the link is a shared original-language word, and use this tool for thematic/teaching links. It also gives a when-to-use payoff ('cite scripture-with-scripture without a second lookup') and covers the lang/edition decision path, including what happens when the localized translation is missing.

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 cover the read-only, closed-world, non-destructive profile, and the description adds substantive behavior beyond them: results are never truncated, chunk overlap means surrounding verses are often returned, and an oversized range yields a mode: range_too_large payload with a focus prompt. That last detail is exactly the kind of non-obvious response behavior an agent needs before calling.

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?

Front-loaded with the core action and scope, then layered with progressively finer operational detail; nearly every sentence carries an actionable constraint. It is dense and slightly over-capitalized in places (ALSO, ASK THE USER), but no sentence is 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?

With no output schema, the description correctly covers the shape of an error-ish return (mode: range_too_large) and the truncation guarantee, which is the crucial part for this tool. It stops short of describing the normal successful return structure or pagination, and leaves book/chapter formatting unaddressed, so it is strong but not exhaustive.

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 only 25% (just verse_end), but the description compensates well by explaining the distinct semantics of verse alone (chunk covering that verse) versus verse_end also (full overlapping-chunk sweep) and the 100-verse cap that the schema states. The remaining gap is `book` and `chapter`, which have no format guidance anywhere — an agent must guess whether "Psalms" or "Psalm 23" style input is expected.

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 and resource (fetch Matthew Henry's commentary) plus scope (a verse or verse range), and explicitly positions itself relative to the sibling get_commentary_section ("Peer of get_commentary_section, not a fallback"). An agent can distinguish it from the other commentary tool without opening either schema.

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?

Gives explicit when-to-call guidance ("Call it when the question concerns a verse's meaning, theology, or application"), spells out the verse-only vs verse+verse_end distinction, and prescribes the exact recovery behavior for range_too_large (ask the user to narrow rather than calling repeatedly). It also names the alternative tool and rules out treating it as a fallback.

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 only say readOnly/non-destructive/closed-world; the description goes far beyond by disclosing that multiple unrelated people can share a name (up to twenty-nine), that ALL of them are returned, that family members carry a follow-on identity string for chained lookups, and that source uncertainty is deliberately preserved via '(?)' and 'Unnamed#N' conventions. It also instructs the agent to disambiguate against verse references and to state residual ambiguity rather than guess — behavioral guidance not encoded in any structured field.

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 purpose and the loudest disambiguation warning are front-loaded, and even the long middle sentence carries non-redundant information. The capitalised CRITICAL clause and the data-quirk conventions are dense but earned; a little of the verse-matching advice could be trimmed without loss.

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 output schema, the description must itself convey return shape — and it does, describing each individual's fields, family links, verse references, and coordinates for places. For a read-only lookup with three well-documented parameters, nothing an agent needs to call it correctly or interpret the response is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why 'name' yields many results, and it clarifies that the identity string is carried on related persons so they 'can look them up in turn' — context the parameter's one-line schema note does not convey. It does not add format detail for strongs_number, so it stops short of a 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 opens with a concrete statement of what the tool resolves ('Who a biblical name actually belongs to') and enumerates the record contents (identity, description, tribe/nation, family, verses, place coordinates). It explicitly contrasts itself with get_word_origin, so an agent can separate it from the lexicon-oriented siblings without opening a schema.

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 gives an explicit trigger ('CALL THIS WHENEVER A QUESTION IS ABOUT A PERSON OR PLACE RATHER THAN A WORD') followed by concrete example question shapes — identity, parentage, marriage, appearance, same-person tests. It also names the alternative tool and the condition that selects it ('For what a WORD means ... use get_word_origin'), which is exactly the when/when-not pairing expected at the top of the scale.

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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description's job is to add what annotations cannot. It does: it discloses the return shape ('curated help text plus the page to link'), explains that the returned url should be used to link the reader, and warns that the tool is the sole source of truth about the site. It does not mention coverage gaps or what happens when a topic is missing, which keeps it short of a 5.

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

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

It is long but front-loaded: the scope statement comes first, then the coverage list, then the call conditions, then the return/linking note. Nearly every clause carries routing or behavioral information. The batch-limit sentence sits oddly at the very end and mildly duplicates the schema, which is the only real structural blemish.

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 lookup tool with a rich 50-value enum and no output schema, the description supplies everything an agent needs: when to call it, when not to, what it returns, and how to use the returned url. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the enum already documents acceptable values and the schema text already advises picking the closest match. The description still adds real meaning by mapping user question domains onto the slug list ('browser extension, installing as an app, accounts and syncing, favorites, the Ten Lists tracker…') and by restating the batch limit of 3 topics per call, which helps the agent construct a valid request rather than guess at granularity.

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 (answer questions) and a precisely bounded resource (THIS WEBSITE / trulyrandomverse.com and its apps), then enumerates the domain areas covered: extension, install-as-app, accounts and syncing, favorites, Ten Lists, search, privacy, donations, reading and study pages. It explicitly contrasts itself with the Scripture-focused siblings ("rather than about Scripture"), so an agent can route correctly without opening any schema.

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 gives concrete call triggers with quoted user phrasings ('how do I…', 'where is…', 'does this site…', 'why did my… change'), plus the exclusion rule that Scripture questions go elsewhere. It also states a hard usage constraint: never answer a site question from memory or by guessing at plausible features, which is exactly the failure mode an agent would otherwise fall into.

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 cover read-only and closed-world safety, but the description adds material context well beyond them: word_study is an AI-written 2025 essay only partly reviewed, citations in it may not contain the cited word, and the recorded data is limited to definition, forms and occurrence count. That caveat is exactly the kind of trust-calibration an agent needs. It stops short of describing response size or error behavior for an invalid Strong's number.

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?

Front-loaded with purpose and return fields, then caveats and sequencing, which is the right order. The AI-essay disclaimer sentence is long and clause-heavy, but each clause carries a distinct warning, so little is truly 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?

With no output schema, the description compensates by listing the returned fields and explaining the meaning and ordering of grammatical_forms. Combined with the data-quality caveat and sibling routing, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including the same H7563/G2316 examples repeated in the description. The description adds only the implicit constraint of a single number; the schema carries the rest, so baseline 3 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?

States a specific verb and resource ('Fetch the full lexical entry and word study for a single Strong's number') and enumerates what comes back (lemma, transliteration, pronunciation, KJV definition, word_study, grammatical_forms). It is clearly distinguishable from get_strongs_for_verse and get_strongs_occurrences, which it names explicitly.

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?

Gives explicit sequencing ('Call this AFTER get_strongs_for_verse when you need to go deeper on a specific word') and names the two sibling tools to use when verifying whether a verse actually contains the word. It also states the intended use of grammatical_forms versus generalizing from memory.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description's job is the payload shape — and it does this in unusual depth: field-by-field semantics for `grammar`, `interlinear.words`, `segments.is_content`, morphology codes, and the Psalms `superscription_words` edge case. It adds no rate limits, pagination, or error behavior, which keeps it below a 5 for a read tool whose result size could vary.

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 core purpose and the alternative-routing sentence are front-loaded, which is good, but the remainder is a single dense paragraph with heavy parentheticals, em-dashes, and ALL-CAPS emphasis that reads like a field reference manual rather than tool guidance. The final Psalms superscription sentence is a genuine edge case but is buried at the end of a very long block; the content earns its place, the packaging does not.

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 output schema, the description carries the full burden of explaining return values and does so thoroughly (grammar, interlinear, segments, morphology codes, superscription). For a 3-parameter fixed lookup the only material omission is the input contract — book naming and verse numbering — which is the one thing a caller must get right before any of the described output can be reached.

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

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

Schema description coverage is 0% and the description never mentions book, chapter, or verse at all. The most error-prone ambiguity — whether `book` accepts "Ps", "Psalms", an abbreviation, or a canonical index, and whether verse numbering follows Hebrew or English convention — is left entirely unresolved despite the description itself raising superscription/verse-1 folding, which is exactly where numbering conventions bite.

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 precise verb+resource (list every Strong's number tagged in a verse) and enumerates the payload (lemma, transliteration, gloss, grammar parse, interlinear). An agent can distinguish this from get_verse_text or get_strongs_detail without opening any schema, since the scope is explicitly verse-scoped and word-level.

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?

"Use this when the user asks about original language, word meaning, or grammar, or when you want to do word-level analysis" gives clear triggering conditions, plus two strong exclusions-as-guidance (never parse grammar from memory, never reconstruct word order from memory). It stops short of naming which sibling to use instead (get_strongs_detail for a lemma-level study, get_word_origin for etymology), so overlap with those remains for the agent to infer.

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 readOnly/non-destructive, and the description goes well beyond them: pagination limit (40 verses), `next_offset` continuation, `by_book` map when paginated, the distinction between `total` (verses) and `uses_in_scripture` (all uses), language/edition defaults, licence-based refusals, and the KJV numbering caveat for certain editions. That is exactly the behavioral context 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 purpose is front-loaded in the first clause, and subsequent sentences each carry operational weight (counting semantics, pagination, phrase search, editions). It is dense and long, but almost every sentence earns its place; slight tightening would push it to a 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?

With no output schema, the description carries the return-value burden and does so thoroughly — explaining `total`, `uses_in_scripture`, `by_book`, `next_offset`, and the fields inside `original`. Combined with the edition and numbering caveats, an agent can call and interpret results without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning beyond the schema by explaining that `total` counts verses (within `book` when given) while `uses_in_scripture` counts every occurrence, that each verse's `original` lists every use there, and by giving concrete `followed_by`/`gap` phrase examples. It largely reinforces rather than duplicates.

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 the exact operation — listing every verse where a Hebrew or Greek word occurs, keyed by Strong's number — and labels it a concordance. This is a specific verb+resource statement that clearly distinguishes it from siblings like get_strongs_for_verse (verse→numbers) or get_strongs_detail (word dictionary entry).

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

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

It gives explicit use cases ('see how Scripture itself uses a word', 'find passages that explain each other') plus the mechanism (pass `book`, `followed_by`, `gap`) for narrowing. It doesn't explicitly name a sibling alternative to route away from, which keeps it from a 5, but the intended context 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 cover the safety profile (readOnly, non-destructive), and the description adds substantial behavior: per-verse fallback to KJV with a `note: "fallback: english"` field, the instruction to translate as you cite, licence-based refusals, and default-edition rules. What it does not state is the actual return shape (field names beyond `note`) or whether a missing reference errors versus returning empty.

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?

Front-loaded with the core action and scope, then layered with the fallback rule and numbering caveat in a logical order. It is dense but nearly every sentence carries operational information; the closing note on Ukrainian/Douay-Rheims/Geneva/Swedish/Serbian versification is genuinely useful but reads long for a caveat that applies rarely.

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 no output schema, so the description carries the return-value burden and partly discharges it (text plus an optional `note` fallback marker). For a tool with five parameters and edition/licence/versification edge cases, it still leaves open what happens on an out-of-range verse or an unsupported lang code, and never names the returned text fields.

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 only 40%, with book, chapter and verse entirely undocumented in the schema, and the description compensates well: it establishes that book/chapter/verse are always KJV numbering in every edition, that end_verse produces an inclusive [verse..end_verse] range capped at 10, and how lang defaults and overrides. It stops short of giving accepted book formats (name vs. abbreviation vs. number), which is the main remaining ambiguity for a required parameter.

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

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

States a specific verb and resource ('Fetch the raw verse text') and bounds scope immediately ('single verse or a small range (max 10 verses)'). The word 'raw' plus the naming of editions distinguishes it from sibling tools like get_commentary_section, compare_versions, and get_strongs_for_verse, so an agent can pick it without opening a schema.

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?

Gives conditional usage for the lang parameter (default conversation language, override for english/other, KJV default outside trulyrandomverse.com/ai) and notes licence refusals. It never routes to alternatives — nothing says to use compare_versions for edition comparison or get_strongs_for_verse for word-level detail — so the agent must infer sibling boundaries.

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 readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered; the description adds the important epistemic constraint that only recorded lexical data is returned and that cognates or reconstructions are outside it. It also previews the return shape. However, it says nothing about occurrence counts, ordering, or what happens with an unmatched Strong's number, so the added behavioral context is strong but incomplete.

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?

Front-loaded with the core action, then the return fields, then the call conditions, then the caveat — a sensible order. The IMPORTANT paragraph is long and slightly redundant with the earlier field list, but it earns its place by setting evidentiary expectations.

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 no output schema, and the description compensates by naming each returned field and explaining what it represents, including the reverse direction and cross-testament linkage. For a single-parameter, read-only lookup tool, nothing an agent needs in order to call it or interpret the result is missing.

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

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

Schema coverage is 100% and the schema itself supplies the format example ("H7563" or "G2316"). The description only implicitly reinforces this by saying 'Hebrew or Greek,' which maps to the H/G prefix. Baseline 3 is appropriate since the schema does the work.

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 and resource ('Trace where a Hebrew or Greek word came from') and immediately enumerates the distinctive outputs — formed_from, words_formed_from_this, related_language_entry, proper-name status, occurrences. That field set differentiates it from get_strongs_detail and get_strongs_occurrences without the agent needing to open either schema.

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 gives explicit trigger conditions: root meaning, etymology, whether two words are related, how a name reached its English spelling. It also carves out a boundary for what the data does not cover. It stops short of naming a sibling alternative for the plain-definition case, so the routing guidance is clear but not exhaustive.

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 readOnly, non-destructive and closed-world, and the description adds substantial behavior beyond that: result ordering tiers, the per-verse `match` classification, `phrase_total` counting, text-language rendering, and refusal of editions whose licence forbids redistribution. The KJV-versification caveat is unusually candid about a subtle correctness issue, which is exactly the kind of context annotations cannot 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 ordering rules are front-loaded well, but the text is a single dense block that packs licence policy, language rendering and edition-numbering edge cases into one wall of prose. The final sentence about Ukrainian, Douay-Rheims, Geneva, Swedish and Serbian Psalm numbering is legitimate but peripheral enough to trim or move to a help 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?

With no output schema, the description carries the burden of explaining returns and does so: it documents `match` values, `phrase_total`, ranking rationale and ordering guarantees. Combined with the language and versification notes, an agent has everything needed to call and interpret this 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 coverage is 100%, so baseline is 3, but the description adds real meaning: `query` must be phrased in English even when `lang` selects another edition, and `lang` governs only returned text while book/chapter/verse stay KJV-numbered. It does not restate the `limit` default or maximum, leaving that to 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 a specific verb and resource: 'Fast keyword search of the KJV', plus the useful scoping detail that the index is English-only. It implicitly distinguishes itself from retrieval siblings like get_verse_text or search_topic_verses by framing the operation as keyword matching, but it never names an alternative, so the differentiation is by implication rather than explicit contrast.

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 thoroughly describes how a query is interpreted (phrase-first, then all-words, then related) and states the edition default and when to pass `lang`, which is genuine usage context. However, it gives no guidance on when to choose this tool over siblings such as search_topic_verses or get_verse_text, and no exclusions or limits on what queries work poorly.

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 readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing the verbatim-quote policy, the deduplication behavior ('also_under'), the excerpt/part mechanism, and the disambiguation response. It does not describe pagination via `limit` or ordering of results, which are the remaining behavioral gaps.

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

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

Front-loaded with the core distinction, then a compact sequence of mode sentences that each carry distinct information, plus a closing block on quote handling. It is dense and long, but nearly every clause earns its place; the quote_id/excerpt material could be tightened.

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

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

There is no output schema, and the description compensates by describing the return shape: profiles with book counts, verbatim quotes with attribution, `quote_id`, `excerpt` parts, and `also_under`. Combined with full schema coverage and annotations, an agent has everything needed to call it and interpret results.

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 adds genuine value by explaining the combinatorial semantics of `father`, `topic`, and `book` — which combinations trigger profile vs. scoped search vs. writer listing — something the per-property schema text does not convey. It says nothing about `limit` or `from_part`, which the schema covers only thinly.

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 and resource ('Search the patristic corpus BY WRITER') and explicitly contrasts it with verse-based search, so an agent can route away from search_topic_verses or keyword_search immediately. The corpus size (62,484 passages from 314 writers) further pins down scope.

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

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

Enumerates the parameter modes with concrete question examples for each: father alone for a profile, father+topic to search within a writer, topic alone across all writers, father+book for one book, nothing for the writer list. It also gives an explicit when-not/alternative rule for ambiguous names ('there are four Gregorys') and tells the agent to ask the user instead of guessing.

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 readOnly/openWorld annotations, the description discloses a lot of non-obvious behavior: returned text follows the conversation language unless lang is passed, missing localized translations surface as `note: "fallback: english"`, editions without redistribution licences are refused, and verse numbering is always KJV. These are exactly the surprises that would otherwise confuse an agent.

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?

It is front-loaded with purpose and usage before the operational caveats, and every paragraph carries information. The final section on differing chapter numbering in Ukrainian, Douay-Rheims, Geneva, Swedish and Serbian editions is dense and arguably the least immediately actionable, but it is not 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?

With no output schema, the description does the work of explaining returns, including the fallback marker field. Ordering of results and whether topics are matched exactly or loosely are left unstated, which are the remaining gaps 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: the default value and platform-dependent behavior of `lang` (conversation language, KJV outside trulyrandomverse.com/ai, licence-based refusal) are not in the schema. `limit` gets no discussion, which keeps this short of a 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 opens with a specific verb and resource: 'Find verses tagged under a biblical topic', and gives concrete topic examples ("covenant", "judgment", "grace"). It is clearly distinct from get_verse_text or get_strongs_for_verse, though it never explicitly contrasts itself with the sibling keyword_search, which is the closest overlap.

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?

'Use this when the user asks about a theme ... and you want canonical examples from across Scripture' gives a clear triggering condition. There is no explicit when-not clause or named alternative (e.g. 'for exact word matching use keyword_search'), so the agent must infer that boundary itself.

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