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

Beyond the readOnly/idempotent annotations, the description adds concrete behavior: response envelope with data/source/status/headers/cache advice, and redirects being reported without following them. No annotation contradiction exists.

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 four focused sentences: purpose first, then constraints, then response behavior. Every sentence earns its place and there is no filler or repetition.

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?

Despite having no output schema and no schema descriptions, the description provides a complete enough picture for invocation: how to discover operations, what input containers to use, what response shape to expect, and how redirects are handled. The readOnly/idempotent annotations cover the safety profile.

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

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

The schema has 0% parameter description coverage, so the description must compensate. It clarifies that parameters holds named path/query inputs and body is only for documented search POST JSON, and it ties operation_id to discovery. However, it does not explain the semantics of service or api_version beyond what the enums show, leaving notable 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 a specific verb and resource: 'Execute any operation discovered with describe_api_operation using its exact input schema.' This clearly differentiates the tool from the discovery-oriented siblings describe_api_operation and discover_apis.

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

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

The description gives clear context: use this only for operations discovered via describe_api_operation, only reviewed routes and read-only methods, and body only for documented search POST JSON. It does not explicitly name sibling tools as alternatives, but the constraints are strong enough to guide correct 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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: hashes are pinned to API versions and TTL is not renewed. This is meaningful extra information for an agent deciding whether to call the 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?

The description is two short sentences with no filler. The core operation is front-loaded, and the important TTL caveat is given its own sentence. Every word contributes.

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

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

The description plus schema covers the input shape and the non-renewal of TTL, but it lacks guidance on what 'compare' returns or how this tool relates to hash-related siblings. Given the nested HashWatch schema and the presence of an output schema, this is adequate but not complete.

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

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

Schema description coverage is 0%, and the description only vaguely refers to 'stored Bible hashes, each pinned to its own API version.' It hints at the api_version and current_hash relationship but does not explain the items array, kind, translation, book, or chapter fields, leaving the agent without enough semantic grounding for the required input.

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 ('Compare') and names the resource ('stored Bible hashes'), and the title clarifies that this is about checking cached scopes for updates. It does not explicitly differentiate from sibling tools such as get_hash or get_hash_manifest, so it falls just short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives like get_hash_manifest or get_hash. The only caveat, 'This does not renew TTL,' is an exclusion but not a usage direction.

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 adds helpful context about service/version scoping and the call_api_operation relationship, but no deeper behavior such as pagination, auth, or error handling is disclosed.

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, each earning its place: the primary action, the follow-up workflow, and the scoping constraint. No redundant boilerplate; key information is front-loaded.

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

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

For a read-only introspection tool with a rich output schema and safety annotations, the description is sufficient to invoke correctly. The required service and api_version are visible in the schema, operation_id's optional list-vs-inspect behavior is implied, and the returned schema's use is explained.

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?

With 0% schema description coverage, the description carries the burden. It compensates by implying operation_id null lists operations while a value inspects one exact operation, and it clarifies that names are scoped by service/version. It stops short of explaining each enum's meaning, so it's not 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 verb and object: 'List operations, or inspect one exact input schema, response schema and parameter meanings.' This clearly differentiates the tool's introspection role from downstream execution via call_api_operation, and the service/version scoping is 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?

It explicitly connects the returned input_schema to call_api_operation, telling the agent what to do with the output. It does not name alternatives like discover_apis or spell out when not to use this tool, but the workflow 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds no additional behavioral context such as pagination, rate limits, or filtering semantics, but it also does not contradict the annotations.

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

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

The description is two short sentences, front-loaded with the tool's purpose, and contains no filler. 'Start here' earns its place by giving workflow context without bloating the description.

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, optional-parameter discovery tool with an output schema, the description is nearly complete. It identifies the tool's role, positions it as an entry point, and the annotations cover safety. The main omission is a brief note on how service and api_version filter the discovery result, though the schema enum values partially compensate.

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

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

Schema description coverage is 0%, so the description should carry the burden of explaining the optional service and api_version parameters, but it only vaguely references 'service/version contracts' without clarifying that these are filters, their defaults, or how null values behave. The schema's enum values are helpful, but the description does not compensate for the lack of parameter documentation.

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 ('supported service/version contracts and their OpenAPI resources') and a clear entry-point verb ('Discover'). It is clearly distinguished from siblings like call_api_operation or get_scripture by positioning this tool as metadata discovery rather than data access or operation execution.

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?

'Start here' gives an explicit usage instruction: this tool is the intended first step in the workflow. It does not name alternatives or exclusions, but the entry-point context is clear enough for an agent to select it before more specific sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining that a changed scope invalidates cached descendants, which is a behavioral consequence beyond what annotations provide. No contradiction with 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?

Two short sentences, front-loaded with the core action and a key consequence. No filler, every word earns its place.

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

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

Despite the output schema covering return format, the 5 parameters (2 required) are completely undocumented. An agent cannot correctly determine how to construct a valid request without additional knowledge. The description is far too sparse for a tool with this parameter complexity and no schema descriptions.

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 provides zero explanation of the parameters. It doesn't clarify what 'kind', 'translation', 'book', 'chapter', or 'api_version' mean, how they relate, or which combinations are valid. The description fails entirely to compensate for the schema's lack of descriptive text.

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 (Fetch) and resource (Bible SHA-1 sidecar), and adds invalidation semantics. It is clear what the tool does, though it doesn't explicitly contrast with the sibling get_hash_manifest, leaving slight ambiguity about the difference between a single hash and a manifest.

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?

No guidance on when to use this tool versus alternatives. It doesn't mention that get_hash_manifest exists or when to prefer one over the other, nor does it specify any prerequisites like needing a translation or book. Usage context is left entirely implicit.

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, and destructiveHint=false, so the description doesn't need to cover safety. It adds the scoping detail (translation/book/chapter) which is useful, but it doesn't disclose any behavioral nuances like result aggregation, pagination limits, or performance expectations, which would be valuable for a bulk operation. With annotations covering safety, a 3 is appropriate.

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

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

The description is a single concise sentence that front-loads the action and scope. There is no unnecessary verbiage, and it conveys the core purpose efficiently. It earns a 5 for conciseness even though it costs some completeness.

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

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

Given 4 parameters with zero schema description coverage, an output schema, and no guidance on parameter construction, the description is far from complete. It doesn't explain how to specify translation/book correctly, what 'kind' values mean, or how api_version affects results. This leaves an agent guessing about valid argument combinations, so a 2 is appropriate.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter explanation. It only hints at scopes ('translation/book/chapter') but doesn't map these to the actual parameters (kind, book, translation, api_version). The mention of 'chapter' is confusing since 'kind' enum has no 'chapter' option. This is insufficient for a 4-parameter tool with zero schema descriptions, so 2 is warranted.

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

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

The description clearly states the verb 'Return' and the resource 'Bible checksums' with scope levels (translation/book/chapter). It distinguishes from sibling 'get_hash' by emphasizing 'bulk checks', making the purpose reasonably specific. However, it does not explicitly contrast with any sibling, so it's not a 5.

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 'for efficient bulk checks' implies when to use this tool, but there is no explicit comparison to alternatives like 'get_hash' or 'check_for_updates'. It offers general context but lacks clear when-to-use vs when-not-to-use guidance, so it's serviceable but not explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: 'before/after .sha consistency checks' and 'Native verse data is preserved, including v3 tokens and spans.' These describe internal checks and output fidelity beyond the annotations, which is exactly what the description should provide.

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

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

The description is two short sentences and a clause. The primary purpose is front-loaded, and every sentence adds value: the scope options, the consistency checks, the preservation detail, and the pointer to the alternative. No fluff or redundancy.

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

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

Given the tool's complexity and that an output schema exists, the description covers the essential decision points: how to request different scopes, what behavioral guarantees exist (consistency checks, data preservation), and when to use a sibling tool. It does not mention return format, but that is likely in the output schema. It could mention that translation is a parameter, but it's implied by 'book or translation.' Overall, it's complete for an agent to call 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 description coverage is 0%, so the description must compensate. It does explain the relationship between book and chapter parameters via omission rules, but it does not explain api_version or translation parameters at all. The translation parameter has a default but its meaning is not clarified; api_version has an enum but the description doesn't mention what v2 vs v3 mean. Since the description only covers two of four parameters, it partially compensates for the schema 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?

The description clearly states the verb 'Read' and the resource 'scripture' with scope options: chapter, book, or translation. It also distinguishes from sibling query_verses by explicitly pointing to that tool for selected references. This is a specific and differentiating purpose statement.

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

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

The description gives explicit instructions on how to select scope: 'Omit chapter for a book, omit both for a translation.' It also names the alternative tool (query_verses) and the condition for using it (selected references). This is strong usage guidance with clear when-to-use and when-not-to-use.

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, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral context that the tool returns book numbers, localized names, and hashes, which is useful but not deeply behavioral. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence that conveys the tool's purpose without waste. It could add a bit more detail about parameters, but it earns its place as concise and structured.

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

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

Given the tool has an output schema, the return values are already documented. The description is adequate for a simple read-only list tool with two optional parameters, but it lacks explicit guidance on when to use it versus siblings like list_chapters or get_hash. The annotations cover safety, so the main gap is usage routing.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'selected API version' and 'translation' implicitly via 'book numbers, localized names and hashes in the selected API version', but it does not explain the meaning or format of api_version or translation beyond what the schema's enum and default provide. Baseline 3 is appropriate because the description adds minimal semantic value over 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 states a specific verb ('Discover') and resource ('book numbers, localized names and hashes') in the selected API version. It clearly distinguishes the tool's purpose from siblings like list_translations or list_chapters, though it doesn't explicitly name a sibling.

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

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

The description implies usage context: it is for discovering book-level metadata in a translation. It does not explicitly state when to use this tool versus alternatives like list_chapters or get_hash, nor does it mention exclusions. The context is clear enough for basic selection but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that it returns 'chapter mappings and hashes' and that it is for discovering identifiers, which is useful. It does not disclose details like pagination or whether hashes are content hashes, but with annotations covering the main behavioral traits, a 3 is appropriate.

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

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

The description is a single sentence, front-loaded with the main action and result. It is concise and every word earns its place. It could be slightly more structured, but it is appropriately sized.

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

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

The tool has an output schema, so return values are documented elsewhere. The description explains the purpose and the discovery workflow. However, with 0% parameter coverage and no mention of required parameters or how to use the output, an agent might not know what 'translation' and 'book' values are expected. The output schema helps, but the description is incomplete for a tool with 3 params and no param docs.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'translation' and 'book' implicitly via 'in a book' but does not explain the meaning of 'translation', 'book', or 'api_version'. The description adds no parameter-level detail beyond the schema's field names and types. With 0% coverage and 3 params, this is a significant 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?

The description states a specific verb ('Return') and resource ('chapter mappings and hashes'), and the title clarifies it lists chapters in a book. It does not explicitly differentiate from siblings like list_books or get_scripture, but the mention of 'discover identifiers before retrieving scripture' gives some context. It is clear enough but not a full sibling differentiation.

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

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

The description implies usage: use this to discover identifiers before retrieving scripture, which is a clear context. It does not explicitly name alternatives or exclusions, but the phrase 'before retrieving scripture' signals when to use it. Given the sibling list includes get_scripture and query_verses, this is adequate but not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value beyond those by specifying the output scope—abbreviations, languages, publisher metadata, and catalog hashes—helping the agent know what to expect. There is no contradiction with 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, tightly worded sentence with no filler. The action and resource are front-loaded, and every word contributes to understanding the tool's purpose.

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

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

For a simple list tool with one optional parameter, strong annotations, and an output schema, the description is sufficient. It names the content categories returned, while the schema handles the api_version default and choices.

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 only parameter, api_version, has no description and is not mentioned in the tool description. However, the schema provides an enum of v2/v3 and a default of v3, making the parameter mostly self-explanatory. The description adds no extra meaning about version implications.

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 action ('Discover') and a precise resource ('translation abbreviations, languages, publisher metadata and catalog hashes'), clearly stating what the tool returns. This also distinguishes it from sibling tools like list_books, list_chapters, and get_hash.

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 'Discover translation abbreviations...' gives an implicit use case: use this tool when you need translation metadata. However, it does not explicitly say when to prefer this over siblings such as get_hash or list_books, nor does it state any 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 mark this read-only, idempotent, and non-destructive. The description adds substantial behavior beyond that: no caching/inferred hashes, error instead of fallback for invalid references, translation default, v3 recommendation, and TTL metadata in response headers.

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

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

The description is compact, front-loads the purpose, and every sentence adds relevant behavioral or selection detail. There is no filler or repetition of schema/annotation content.

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

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

With an output schema available, the description does not need to explain return values, and it covers error behavior, caching behavior, defaults, version choice, and TTL metadata. The only notable gap is the lack of explicit routing guidance relative to sibling 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 coverage is low (33%), and the description adds only minimal parameter guidance: 'Translation defaults to kjv' and 'Use v3 for richer verse data,' with the default already present in the schema. It does not explain accepted translation values or API-version behaviors beyond the v3 recommendation.

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 operation ('Fetch native reference results') and the title clarifies the resource ('selected or grouped verses'), so an agent can tell it is a verse-querying tool. It does not explicitly name sibling tools like search_verses or get_scripture, but 'without caching or inferred chapter hashes' suggests a differentiator.

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 conveys that the tool works on exact native references, that unresolved references error instead of falling back, and that v3 should be preferred, which gives some contextual guidance. It does not explicitly state when to use query_verses versus sibling tools such as search_verses, get_scripture, or list_chapters.

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=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail beyond these: it explains the operation mechanism ('Fetches the current index and filters it locally, returning a bounded page of unchanged records'), details matching semantics (case and accent insensitivity via Unicode NFD, exact case-sensitive ID matching), and clarifies that see_also and backlinks are directed links, not synonyms. No contradictions with annotations.

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

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

The description is front-loaded with purpose and prerequisites, then provides essential behavioral details. Each sentence adds value: the first sentence defines the scope, the second gives discovery prerequisite, the third explains the filtering behavior, and subsequent sentences cover matching semantics, exclusions, pagination, and follow-up actions. There is no redundancy or fluff.

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 tool with pagination, multiple match modes, and a dependency on dictionary discovery, the description covers all critical aspects: discovery step, search criteria, matching behavior, pagination, and how to use results. It also addresses potential misinterpretations (not full-text search, see_also not synonyms). Since an output schema exists, return format details are not required in the description.

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?

With 0% schema description coverage, the description must compensate for the lack of parameter documentation. It does so by explaining the query parameter (matching semantics), the match parameter (exact/prefix/contains with default), pagination (offset/limit via next_offset), and the dictionary parameter (discovered modules). However, it does not explicitly enumerate each parameter name, leaving some inference to the agent. This is a minor gap given the clarity provided.

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

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

The description clearly states the purpose: 'Find entry IDs by key, alias, search text or ID in a discovered dictionary module.' It also distinguishes from siblings by explicitly noting 'This is not definition full-text search.' This differentiates it from search_verses or query_verses, making the tool's scope unambiguous.

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

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

The description provides explicit usage guidance: it instructs to 'Discover modules with dictionaries/v1/listDictionaries first,' explains when not to use it ('This is not definition full-text search'), and directs next steps ('Fetch definitions with dictionaries/v1/getDictionaryEntry and the returned exact ID'). It also clarifies pagination ('Follow next_offset with the same inputs') and default vs explicit match modes ('Exact is the default; use prefix or contains explicitly if needed').

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, and non-destructive behavior, so the description adds valuable non-obvious details: results are never cached, searches recognized as references may bypass filters, and pagination metadata should be inspected. These are genuine gotchas beyond the structured annotations.

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

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

The description is compact and front-loaded with the core purpose, using fragmented notes to pack in edge cases. It avoids fluff, though phrases like 'book/exclude repeat query keys' are terse enough to be cryptic.

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

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

Given the high complexity (15 parameters, 6 enums) and 0% schema coverage, the description covers only a few quirks. It omits guidance on major query controls like limit/offset, sort, matching mode, scope, translation, and case sensitivity, leaving an agent under-equipped for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it only mentions book/exclude/books/proximity and words=all. Most of the 15 parameters—search, sort, limit, offset, scope, match, diacritics, api_version, translation, case_sensitive—receive no semantic guidance in either the schema or the description.

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

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

The description states a specific verb and resource: 'Search text' with 'all native filters and pagination', which clearly indicates a text search operation. However, it does not explicitly differentiate this tool from sibling query_verses, though the title 'Search Bible text' anchors the subject.

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 offers usage constraints such as 'proximity requires words=all', 'books is comma-separated', and warns that a reference-recognized search may bypass filters. It also directs users to describe_api_operation for the equivalent JSON POST, but it does not clearly state when to choose search_verses over query_verses or other siblings.

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