FLOGVIT.bible

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is fully covered. The description usefully discloses the sections returned (author, date, audience, structure, themes), but says nothing about behavior on unknown book names or missing content.

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?

A single sentence, front-loaded with the object and the output dimensions; every clause carries information and there is no 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?

For a simple two-parameter read tool with rich annotations, full schema descriptions, and no output schema, the description is nearly sufficient; only failure behavior for unrecognized book names is left unstated.

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%: 'book' accepts any language and 'language' is enum-documented with an explicit English fallback. The description adds no parameter-level meaning beyond that, so the 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 concrete resource (an introduction to a whole book of the Bible) and enumerates the content it covers: author, date, audience, structure, main themes. That distinguishes it from passage- or chapter-level siblings, though the description never names those siblings 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?

The phrase 'a whole book' implies book-level scope versus get_chapter_study or get_passage, but there is no explicit when-to-use statement, no mention of alternatives, and no guidance on when a book overview is inappropriate.

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 safety and idempotency, and the description adds substantial value by disclosing the content payload beyond annotations. It does not describe return format or error behavior, but the content enumeration is meaningful behavioral context for a retrieval tool.

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

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

Two sentences, front-loaded with what the tool returns, followed by the essential input constraint. The dense content list earns its place by telling the agent exactly what to expect.

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 adequately compensates by listing the content categories returned. Annotations cover safety, and the schema documents parameters fully. Return format or data shape is left implicit, which is a minor gap.

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 important semantic meaning beyond the schema: the reference must target a chapter, and any verse portion is ignored, which prevents a common misuse of the richly documented reference 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?

The description uses a specific verb (get study content) and resource (one chapter), and enumerates the exact content types returned: summary, historical context, key words, people, themes, stories, prophecies, gospel parallels, timeline events. It clearly distinguishes chapter-level study from book-level or passage-level siblings.

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

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

It gives clear context: pass a chapter reference like "Rom 8" and note that verses are ignored. That is a useful usage constraint, but it does not explicitly name alternatives (e.g., use get_passage for verse text) or state when to choose this over get_book_overview.

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, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine behavioral context the annotations lack: the result is organized per verse and each entry carries a short explanatory note, which shapes how an agent should present it.

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?

Compact and front-loaded: what you get comes first, the follow-up action second. The parenthetical earns its place as an invocation hint, though the sentence boundary between the two ideas is slightly awkward.

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?

No output schema exists, but the description conveys the essential return shape (related passages keyed to each verse, each with a note), and language/format details live in the schema. Sufficient for an agent to call and use 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 reference format examples, semicolon multi-reference syntax, and language fallback are all already documented in the schema. The description's ';' tip restates the schema rather than adding new meaning, so the 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 the resource precisely: related passages for each verse of a passage, plus a note explaining the relation. This distinguishes it from get_passage (which retrieves the actual text) and from the search_* siblings, though the verb 'get' is carried only by the tool name.

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 a concrete follow-up workflow: fetch the returned references with get_passage, batching several in one call with ';'. It never states when to prefer this over siblings like get_chapter_study or search_bible, so the choice is left to inference.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that a short note accompanies the verse; it says nothing about how the daily verse is chosen, whether it changes at midnight or in which timezone, or what happens if today's verse is unavailable. Useful but thin given the low bar set by the annotations.

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

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

A single short sentence with the resource front-loaded and no filler. Nothing is wasted, though the terseness is part of why coverage gaps exist elsewhere.

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 must convey the return shape, and 'a short note' is very vague — no indication of note length, structure, or whether reference/citation is included. Combined with the entirely unexplained edition parameter, an agent lacks enough to call this confidently with non-default arguments.

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 50%: the language parameter is well documented in the schema including fallback-to-English behavior, but the edition parameter has no description anywhere and its enum values (osnb, osnn, osen) are opaque abbreviations. The description does not compensate at all — it never mentions editions or languages, leaving an agent unable to choose sensibly.

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 resource ('Today's verse on bible.flogvit.com') and adds the deliverable ('with a short note'), so an agent can tell this is a daily devotional retrieval rather than an arbitrary passage fetch. It does not explicitly contrast itself with get_passage, but the temporal qualifier 'Today's' does most of the differentiation work.

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?

There is no statement of when to use this versus get_passage, get_chapter_study, or search_bible, and no note that the verse is date-driven and therefore not selectable by the caller. Usage can only be inferred from the word 'Today's'.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond them: the underlying critical texts and the fact that the word explanations are authored in Norwegian and must be translated for the user — an important behavioral caveat that isn't 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?

Two tight sentences, front-loaded with what is returned, followed by the one caveat an agent actually needs (Norwegian explanations). Nothing is padded or redundant.

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

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

For a read-only lookup with no output schema, the description covers what comes back, the optional per-word expansion, the source editions, and the language caveat on explanations. Multi-reference and language-fallback mechanics are already covered by the schema, so nothing an agent needs to call 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 67%; the undocumented gap is word_by_word, and the description explicitly explains what that flag turns on ('word by word with an explanation of each word'), which is beyond what the schema offers. The language and reference parameters are already well described in the schema, so no further compensation is needed.

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

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

The description states a specific resource (the Hebrew or Greek source text of a passage) and names the textual basis (Leningrad Codex, SBLGNT), plus a word-by-word mode. It is clearly distinct from a translation-oriented sibling like get_passage, though that distinction is implied by the word 'original' rather than stated 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?

Usage is implied: reach for this when the user needs the source-language text rather than a translation, and enable word-by-word when per-word explanation is wanted. There is no explicit when-to-use / when-not clause and no sibling (e.g. get_passage) is named, leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds genuine behavior: results come side by side per edition and include a chapter URL, and include_notes enumerates the kinds of scholarly content returned.

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

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

Two sentences, front-loaded with the core return behavior and then the optional-flag guidance. Nothing wasted and nothing buried.

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 adequately sketches the return value (text per edition, chapter link, optional footnotes). It is a read-only tool with annotations carrying the safety profile, so coverage is strong, though error/fallback behavior for invalid references is left implicit.

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 goes further by enumerating what include_notes actually contains (translation choices, Greek/Hebrew linguistics, textual criticism, history, theology), which meaningfully expands on the schema's terse one-liner.

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?

A specific verb and resource: it returns passage text, side by side across editions, plus a chapter link. The side-by-side framing implicitly separates it from get_original_text and get_chapter_study, but no sibling is named, so the differentiation is inferred rather than stated.

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 one conditional hint — use include_notes for footnotes — but never says when to pick this tool over search_bible, get_chapter_study, or get_original_text. Usage is implied by the purpose rather than stated.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds value by disclosing the returned content sections, including that key events come with the passages where they occur — meaningful payload context that is not in any other 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?

A single front-loaded sentence listing the payload sections in order of likely interest. Nothing is repeated from the schema or annotations and nothing is wasted.

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

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

With no output schema, the description must convey what comes back, and it does list the top-level sections and notes that events are tied to passages. It stops short of describing the response shape or whether family/related-people entries are ids, names, or nested records, which is the remaining gap for a detail 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%: the id parameter documents its origin (search_people, get_chapter_study) with an example, and language documents the enum plus English fallback behavior. The description adds no parameter meaning of its own, so the 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?

The description enumerates exactly what a person record contains (summary, family, related people, key events with their passages), which makes the resource and payload clear. It is a noun phrase rather than an explicit verb+resource statement and does not name sibling tools, so differentiation from search_people rests on the schema's id note.

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?

"One person:" implicitly frames this as the single-entity detail lookup as opposed to the plural search_people, and the schema's id description routes the agent to search_people to obtain an id. However, the description itself contains no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds only that the response includes the source passages the entry is built on; it says nothing about size, missing-language fallback behavior, or what an "entry" contains, which matters more here since there is no output schema.

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, front-loaded with the resource and immediately followed by the provenance constraint; nothing is padded or repeated. It is perhaps a touch terse for the amount of ambiguity in the kind parameter.

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?

No output schema exists, so the description must sketch the return value, and "the passages it is built on" does part of that job. It leaves unclear how the four kinds change the entry shape and how a missing translation degrades the response — meaningful gaps for a 3-parameter lookup.

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 33% — language has a good inline description, but id and the four-value kind enum are undocumented in the schema. The description adds nothing about what kind means (story vs theme vs prophecy vs parallel) or whether id is global or kind-scoped, so the coverage gap is unmitigated.

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 full entry for an id" states a clear retrieve-by-id operation on a specific resource, and it names the sibling tools that produce the id, which distinguishes it from search_topics and get_chapter_study. The title supplies the kind vocabulary (story, theme, prophecy, parallel) that the description itself never restates.

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 says the id must come from search_topics or get_chapter_study, which is a real precondition that routes the agent correctly inside the sibling set. It stops short of saying when not to use it (e.g. versus get_passage for raw text) or what happens if the id is stale.

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 this is a read-only, idempotent, non-destructive, closed-world call, so the safety profile is fully covered elsewhere. The description adds substantive domain context about each edition's provenance (open translations vs. source texts), but says nothing about return shape, ordering, or size, which is the remaining behavioral gap.

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

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

Two sentences, front-loaded with the core answer ('editions available, with language and licence') followed by enumerative detail. No filler, though the parenthetical edition-code catalogue is dense and could be formatted as a list for faster scanning.

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

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

With no parameters, no output schema, and full annotation coverage, the description carries an appropriate load: it explains what the call yields and what each returned edition means. An agent has enough to call it and interpret results, though it lacks explicit routing to the tools that consume edition codes.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool whose description does not need to compensate for schema gaps.

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 the resource clearly: 'The Bible editions available, with language and licence.' The verb is implied rather than stated ('List' appears only in the title), but the scope and return content are unambiguous. None of the sibling tools deal with editions, so differentiation is implicit through the noun alone.

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?

Usage is only implied — an agent can infer this is a reference/lookup call to discover edition codes before using search_bible or get_passage, but the description never says so or names which sibling tools consume these codes. No when-not guidance is given, though a zero-parameter catalogue tool has little ambiguity about when to invoke it.

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

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

Annotations already declare a read-only, idempotent, non-destructive operation, so the description is free to spend its words on matching semantics. It does disclose non-obvious behavior: AND-across-all-words matching, substring/stem matching, and exact-phrase quoting. It does not address result ordering or paging 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?

Three tight sentences, each earning its place: match semantics first, phrase syntax second, edition/language selection last. No filler or restatement of the name.

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?

Covers the matching model and the highest-risk parameter choice for a 7-parameter search tool; safety is covered by annotations and no output schema is declared. Pagination (limit/offset) and the fact that results are presumably paged are not mentioned, which is the one remaining gap.

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 57%, and the description compensates by explaining the two trickiest parameters: query semantics (substring stems, quoted phrases, all-words-required) and edition-to-language mapping. book, limit, offset, testament, and language are left to the schema, which documents most of them adequately.

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 ("Finds verses containing ALL the given words") plus the scoping constraint "in one edition". This clearly distinguishes it from search_original_word, search_topics, and search_people, which target other match dimensions.

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 prescriptive guidance on choosing the edition to match the word language (osen for English, osnb/osnn for Norwegian, sblgnt/tanach for Greek/Hebrew), which prevents the main misuse. It does not, however, explicitly say when to use a sibling instead, e.g. search_original_word for lemma-based lookup.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the bar is lower. The description still adds real value by disclosing the accent/cantillation-insensitive matching rule and the side-by-side source/translation return shape, though it says nothing about result capping via limit/offset.

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

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

Two sentences, zero filler, with the core behavior front-loaded and examples used efficiently to illustrate the normalization rule and the expected input script.

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 five parameters and no output schema, the description usefully covers the return shape (source text and translation side by side), which would otherwise be unknowable. The gap is pagination: default limit 20 and offset are never mentioned, so an agent may believe it receives every verse.

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?

At 60% schema coverage, the description contributes the script requirement for `word` and implies `edition` supplies the translation column. It adds nothing for limit, offset, or the `language` parameter, which controls names/notes/study content and could surprise an agent.

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: finds every verse where a Hebrew or Greek word occurs, with concrete examples (ἀγάπη, λόγος, חֶסֶד). It is clearly distinguishable from text-search siblings, though no sibling is named 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?

The description implies the use case (word-level lookup rather than passage lookup) and notes that accents and cantillation are ignored, which matters for query construction. However, it never states when to prefer this over search_bible or get_original_text, and gives no exclusions.

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, idempotent, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description's only added behavioral fact is that results are ids rather than full records, which is useful but thin; nothing is said about match fuzziness, result limits, or ordering.

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 tight sentences, no filler. The searchable scope is front-loaded and the follow-up tool pointer is placed last where it is most actionable.

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 discloses that ids are returned and names the tool that consumes them, and the language fallback lives in the schema. Minor gaps remain around matching behavior and result volume, but nothing an agent needs 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 50%: the language parameter is fully documented with an enumeration and fallback rule in the schema, while query is only constrained to minLength 2. The description compensates by demonstrating that query accepts descriptive phrases ('king Judah', 'prophetess'), not just bare names, adding real meaning beyond the schema.

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

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

States a specific verb (Finds) and resource (people), and crucially defines both query modes: by name or by what is said about them, with concrete examples. This distinguishes it cleanly from siblings like search_bible, search_topics, and get_person.

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 closing clause 'Returns ids for get_person' implicitly routes the agent: use this to discover a person, then call get_person for detail. That is a clear usage relationship, though it never states exclusions or when a direct get_person lookup is preferable.

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, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful domain scope and return behavior by saying it returns ids for get_topic, but it does not describe ranking, pagination, result limits, or matching 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 front-loaded with the action and resource, then lists concrete content categories with compact examples. Every sentence carries information, and there is no redundant restatement of the tool name or annotations.

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 simple two-parameter search tool with annotations covering safety and no output schema, the description is largely complete: it states the search domain, examples of query content, and that results are ids for get_topic. The main missing piece is explicit guidance on when to choose this search tool over sibling search tools.

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 50%: the language parameter is well documented in the schema, including enum values and English fallback behavior, while the query parameter has no schema description. The description partially compensates by giving examples of acceptable query types, such as 'prodigal son' and 'forgiveness,' but does not explain matching semantics or whether search is fuzzy, exact, or keyword-based.

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: it searches study material and enumerates concrete content types such as Bible stories, themes, prophecies, gospel parallels, and timeline events. It also names the follow-up tool, get_topic, which clarifies output purpose, though it does not explicitly distinguish itself from sibling search tools like search_bible or search_people.

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?

Usage is implied by the phrase 'Returns ids for get_topic,' which signals a two-step workflow: search here, then retrieve details with get_topic. However, there is no explicit guidance about when to use this instead of search_bible, search_people, or other sibling search tools, and no exclusions are stated.

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