Urantia Papers

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by disclosing that the tool accepts three different paragraph reference formats (globalId, standardReferenceId, paperSectionParagraphId), which is useful for correct invocation and not captured 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?

The description is exceptionally concise: two sentences with no extraneous information. The first sentence states the core purpose, and the second clarifies input formats. 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?

The tool is simple (one parameter, read-only, output schema present). The description covers the essential behavior and input flexibility. With annotations and an output schema, nothing critical is missing for a getter of this nature.

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?

Although the schema covers the parameter with a description and example, the description goes significantly beyond by providing concrete examples of all three accepted reference formats. This adds valuable meaning and reduces ambiguity for the agent, exceeding the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Get the audio file URL for a specific paragraph.' It uses a specific verb and resource, and the mention of multiple reference formats distinguishes it from sibling tools like paragraphs.get or bible.verse, which focus on text/content.

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 to retrieve audio for a specific paragraph, and it emphasizes that any paragraph reference format is accepted. However, it does not explicitly mention when not to use it or name alternatives, stopping short of the highest score.

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, non-destructive, and closed-world, so the safety profile is fully covered. The description adds that the metadata includes chapter and verse counts, which is modest extra context; it adds nothing about error behavior for unknown book codes.

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 with no filler, and the core purpose is front-loaded before the identifier-format detail. The second sentence is dense but every clause (code systems, case, separators) carries information an agent needs.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile, so the identifier-format guidance is the main remaining gap and it is handled. Minor shortfall: no mention of what happens when a book code is not recognized.

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 beyond the schema examples: it enumerates accepted identifier systems (OSIS, USFM, full names, aliases) and states matching is case-insensitive with hyphens/underscores tolerated. That tolerance rule is not stated in the schema and materially affects how an agent constructs the call.

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 metadata for a single Bible book') and names the payload ('chapter and verse counts'). The word 'single' implicitly contrasts with the sibling bible.books list tool, though that sibling is never 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?

Usage is only implied: an agent can infer this is for one book versus bible.books for many, but the description never says when to prefer this over bible.books, bible.chapter, or bible.verse. No exclusions or prerequisites are given.

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, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: the listing is unconditional and complete at exactly 81 entries, with a stated canon breakdown, implying no filtering or pagination. It does not mention the lang parameter's effect on results, which is the one 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?

One tightly packed sentence: scope first, composition second, returned fields third. No filler, no 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?

With an output schema, full annotation coverage, and 100% schema description coverage, the description only needs to establish scope and shape — which it does. An agent knows what it gets (all 81 books with codes, names, canon, counts) and needs nothing else to call it correctly.

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

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

Schema description coverage is 100% and the single lang parameter is documented exhaustively in the schema, including the es/eng distinction and the catalogTranslation label. The description says nothing about lang, so it adds no meaning beyond the schema; 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 (list all 81 books) and pins the scope precisely: 39 OT + 15 deuterocanonical + 27 NT. The plural 'all books' distinguishes it from the singular bible.book sibling, and the enumerated fields tell the agent exactly what a listing yields.

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 'list all' — an agent can infer this is the enumeration entry point before drilling into bible.book or bible.chapter. However, there is no explicit when-to-use guidance, no mention of the bible.book alternative, and no stated precondition (e.g., 'use this first to discover OSIS codes').

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses useful behavioral details: verses are returned ordered by verse number, and book_code accepts multiple formats (OSIS, USFM, full name, alias). This adds meaningful context without contradicting 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 exactly two sentences, front-loaded with the core function and immediately followed by a useful nuance about book_code. Every sentence earns its place with no repetition of schema or annotation data.

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, idempotent tool with a full output schema and 100% parameter coverage, the description is complete. It covers the main behavior (returning all verses in order) and input flexibility, leaving no significant gaps.

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

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

The input schema already describes both parameters with 100% coverage, providing a baseline of 3. The description goes further by clarifying accepted formats for book_code (OSIS, USFM, full name, alias), which is not fully explicit in the schema and adds practical guidance.

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 action ('Get every verse in a Bible chapter') with a clear resource and output ordering ('ordered by verse number'). This clearly distinguishes it from sibling tools like bible.verse, which likely returns a single verse.

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 clearly indicates this tool is for retrieving an entire chapter, which establishes a clear usage context. It does not explicitly mention alternatives or when-not-to-use cases, but the purpose statement itself provides strong 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 readOnly, idempotent, non-destructive, openWorld behavior, so safety is covered. The description adds genuine behavioral context beyond them: results are cosine-ranked and each one carries a set of attached cross-corpus Urantia paragraphs, so the agent understands the return shape is enriched, not just Bible hits.

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 operation and its enrichment are front-loaded, and the filter notes come last. It is efficient overall, but the sentence about top-N Urantia paragraphs and the following 'One query surfaces both Bible matches and the relevant Urantia content' partially repeat the same idea and could be merged.

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

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

With an output schema present, the description needn't explain return values, yet it usefully clarifies that results are enriched with Urantia paragraphs. Filters and the disable flag are covered. The main gap is the absence of any routing hint relative to the other semantic/fulltext siblings, but nothing needed 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 description coverage is 100%, so the schema already documents every parameter, including the canon enum values and the meaning of urantia_parallel_limit=0. The description restates canon, book_code, and the 0-disables behavior without adding syntax, defaults, or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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?

It states a specific verb and resource ('free-form natural-language search across all Bible chunks') plus the ranking method ('ranked by cosine similarity') and the distinctive enrichment ('top-N pre-computed Urantia paragraphs'). The Bible/works domain split makes it separable from siblings like works.search.semantic and search.semantic 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?

Usage is implied by 'free-form natural-language' versus the sibling search.fulltext, but the description never explicitly says when to prefer this over search.semantic, works.search.semantic, or search.fulltext, nor does it name any exclusion conditions. The only explicit usage note ('set urantia_parallel_limit to 0 to leave out the Urantia paragraphs') is parameter-level, not tool-selection 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, idempotentHint, and destructiveHint, covering safety. The description adds valuable context beyond annotations by specifying the translation (World English Bible) and listing accepted formats for book_code (OSIS, USFM, full name, alias), which gives insight into input flexibility.

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 exceptionally concise: two sentences that front-load the core purpose ('Get a single verse') followed by a necessary detail about book_code formats. No wasted words 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?

With strong annotations (read-only, idempotent), an output schema, and a description that covers purpose, source translation, and book_code flexibility, the tool's usage context is fully specified. Nothing critical is missing for this simple read tool.

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

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

The schema provides basic descriptions for all parameters (100% coverage), but the description adds significant meaning for book_code by enumerating accepted formats (OSIS, USFM, full name, alias). This goes beyond the schema's simple 'Book identifier' and example.

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

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

The description clearly states the tool's function: 'Get a single verse from the World English Bible (eng-web).' It uses a specific verb and resource, and the 'single verse' distinction differentiates it from sibling tools like bible.chapter and bible.book.

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 for fetching a single verse, which is clear context, but it does not explicitly mention alternatives or when-not-to-use scenarios. The sibling tool names (e.g., bible.chapter) help infer boundaries, but the description itself does not name them.

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, and the description adds substantially beyond that: it discloses the result cap (top 10), that values are pre-computed at seed time, the embedding model and dimensionality, cosine similarity as the metric, and the score (0..1) and rank (1..10) ranges. The 'semantic neighbors, not curated parallels' caveat is a genuine behavioral disclosure that prevents misuse.

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 with the core behavior front-loaded and the caveat placed strategically at the end. The embedding-model/dimension detail ('text-embedding-3-large (3072-d)') is mildly implementation-flavored, but it supports interpretation of the similarity scores.

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 a full output schema, the description supplies everything needed: what is returned, how many results, how they are scored and ranked, and the crucial caveat that these are not curated parallels. Return-format explanation is correctly delegated to the output schema.

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

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

Schema description coverage is 100% with three required parameters (book_code, chapter, verse) each documented, so the schema carries the parameter burden. The description adds no additional semantics about parameter format, valid book codes, or out-of-range behavior, making the baseline 3 appropriate.

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: returns the 10 Urantia paragraphs whose embeddings are nearest to the Bible chunk containing the given verse. The embedding/similarity framing clearly distinguishes it from siblings like bible.verse (plain verse lookup) or search.semantic (generic search).

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 line 'These are semantic neighbors, not a curated list of parallels' gives a clear interpretive caveat that shapes how an agent should use the results. It does not, however, name an explicit alternative or state when-not to use it versus search.semantic or bible.verse, so it falls short of full 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the accepted ref forms and the formatting styles, which is modest but real context beyond the annotations, and nothing about auth or limits is needed for a pure read.

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 what the tool returns, followed by the input format. 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?

An output schema exists so return structure need not be described, and the input forms and styles are covered. The only gap is the absence of when-to-use guidance relative to the many sibling read tools, which is minor for such a simple, deterministic operation.

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 would be 3, but the description goes further by showing three accepted ref shapes ("196:2.1", "1:196.2.1", "196.2.1") where the schema only illustrates one, adding genuine format guidance for the 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+resource: produces a formatted citation of one paragraph, and names the four supported styles. It is clearly distinguishable from siblings like paragraphs.get or quotes.verify, though it does not explicitly contrast itself against any of them.

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 never states when to choose this tool versus paragraphs.get or quotes.verify, nor any prerequisites (an existing ref, a paper lookup). Usage is only implied by the name and the mention of citation styles.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The sentence enumerating returned fields adds some expectation-setting, but a dedicated output schema exists, so this partially duplicates structured data and omits behavior like what happens for an unknown slug.

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: the action and keying first, the payload second. Nothing is redundant or padded, and the most decision-relevant information leads.

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, annotated read tool with an output schema, the description is essentially sufficient. The only meaningful omission is error behavior (e.g., nonexistent slug), which matters mildly for a lookup 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?

There is a single parameter with 100% schema description coverage, including a concrete example ('god-the-father'). The description reinforces the slug semantics ('by its slug ID') but adds no format or validation detail 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 and resource ('Get detailed information about a specific entity') plus the keying mechanism ('by its slug ID'), which implicitly separates it from entities.list and entities.paragraphs. It stops short of naming a sibling explicitly, 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 phrase 'a specific entity by its slug ID' implies the caller must already know the slug, which points toward entities.list for discovery, but no alternative or precondition is ever named. Usage is implied, not guided.

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 behavior, so the safety profile is covered. The description adds scoping context (the corpus is the Urantia Papers) but says nothing about ordering, pagination limits, or result shape beyond what the annotations and output schema supply.

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 waste: the first defines the catalog and its contents, the second states capabilities. Purpose is front-loaded ahead of optional functionality.

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

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

With an output schema present, return values need no explanation, and all five optional parameters are fully described in the schema. Only pagination expectations (default 20, max 100, paging through a large catalog) are left unaddressed in prose, 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 description coverage is 100%, so every parameter including the q/query alias is documented structurally. The description's 'filtering by type and searching by name' loosely maps to type and query but adds no detail on matching behavior (name vs alias, partial vs exact) beyond the schema's own 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 and resource ('Browse the entity catalog') and enumerates exactly what the catalog contains — beings, places, orders, races, religions, concepts from the Urantia Papers. It is clearly a listing tool, distinguishable in intent from entities.get, though it never names that sibling 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 by 'Browse' plus 'Supports filtering by type and searching by name', which tells the agent the two main modes. But there is no explicit guidance on when to prefer this over entities.get, search.fulltext, or entities.paragraphs, and no stated preconditions.

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 and closed-world, so the safety profile is fully covered. The description adds the useful ordering trait ('ordered by position in the text') but says nothing about pagination behavior or result volume, which matters for a tool returning 'all' paragraphs.

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 waste, with the core operation and its ordering guarantee front-loaded. Nothing is repeated from the title or schema.

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

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

With a full output schema, complete parameter descriptions, and rich annotations, the description only needs to convey the operation and ordering, which it does. Minor gap: it does not hint at result size or pagination expectations for a potentially large result set.

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

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

Schema description coverage is 100%: entity_id slug format with an example, page and limit with defaults and bounds are all documented in the schema. The description adds no parameter detail beyond that, so the baseline of 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 ('Get all paragraphs that mention a specific entity') plus the ordering guarantee, so the agent knows exactly what it retrieves. It stops short of naming how it differs from near siblings like paragraphs.context or paragraphs.get, leaving the distinction to inference.

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 clause 'Useful for studying everything said about a particular being, place, or concept' implies a use case but gives no when-not conditions and names no alternative tool. An agent must guess whether to prefer this over paragraphs.context or search.fulltext.

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 safe, read-only, idempotent operation, so the bar is lower. The description adds useful value by explaining response shape — paragraphs carry reference, section, and plain text, paper.audio may be null, and entity mentions are optional — which goes beyond what annotations 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 compact and front-loaded: purpose first, then ID range, then paragraph/audio details, then the optional entity flag. Every sentence carries useful information, with little or 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?

With an output schema, rich annotations, and 100% schema coverage, the description supplies enough context to call the tool correctly. The main omission is that it does not mention the lang parameter's effect on response shape (Spanish translation labels), though the schema covers it.

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

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

Schema description coverage is 100%, so the schema itself fully documents paper_id, lang, and include_entities. The description adds only minor context beyond that, notably that ID 0 is the Foreword, while the linguistically significant lang parameter is left entirely 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 states a specific verb and resource ('Get a single paper with all its paragraphs') and clarifies the scope with paragraph contents. It implicitly distinguishes itself from papers.list and paragraphs.get by emphasizing that a whole paper fits in one call, though it does not name 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 'so a whole paper fits in one call' hints at using this tool when the full paper is needed rather than making repeated paragraph calls. However, there is no explicit statement of when to use this versus papers.sections, paragraphs.get, or papers.list.

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, non-destructive and closed-world, so the safety profile is fully covered. The description adds that the result is a flat, complete set of 197 items with metadata only (no paragraph text), which is useful context, but it says nothing about how the lang parameter changes titles/labels or about ordering/pagination.

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 action and scope, with the returned fields enumerated inline. 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?

For a single-optional-parameter read tool with an output schema, the description covers scope, count, and returned fields adequately. The only small gap is not noting that lang switches titles/paragraph labels, which the schema does cover.

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

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

Schema description coverage is 100% and the single lang parameter's enum is thoroughly documented in the schema, including the Spanish translation caveat. The description does not mention lang at all, so it adds nothing beyond the schema; 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 (List) and resource (all 197 papers of the Urantia Papers), and enumerates the returned metadata (id, title, partId, labels). The phrase 'as a flat list' implicitly contrasts with the hierarchical papers.sections and the single-item papers.get, so an agent can distinguish it without opening the 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?

Usage is implied — use it to enumerate the paper index — but there is no explicit statement of when to prefer it over papers.get, papers.sections, toc.get, or search.fulltext. No prerequisites or exclusions are given.

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, and closed-world, so the safety profile is fully covered. The description adds one genuine behavioral fact beyond that — results come back sorted by section number — but reveals nothing about scope limits or whether content is included.

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, zero filler, with the core retrieval behavior front-loaded and the rationale second. Every clause 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?

With an output schema present and full parameter documentation, the description need not explain return shapes; annotations carry the safety profile. The only ambiguity is whether 'all sections' means section listings/metadata or full section bodies, which would help an agent choose between this and paragraphs.get.

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

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

Schema description coverage is 100%, with paper_id's format/example and lang's enum semantics fully documented in the schema itself. The description adds no parameter-level meaning (e.g. how lang affects section titles), so the baseline of 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 ('Get all sections within a paper') plus a scope qualifier ('ordered by section number'). It is clearly distinguishable from papers.get and paragraphs.get by name and content, but it does not explicitly name or contrast with any 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?

'Useful for understanding paper structure before reading specific sections' gives a concrete workflow context for when to reach for this tool. It stops short of naming the alternative tool (e.g. paragraphs.get) for reading actual section content, so 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.

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world, so the safety profile is done. The description adds a genuine behavioral constraint not in the annotations: context is bounded 'within the same paper', meaning the window truncates at paper edges rather than pulling in neighbouring papers.

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 with the core behavior front-loaded. The trailing clause 'Useful for understanding passages in context' is slightly redundant with 'with surrounding context' but is not costly.

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?

An output schema exists so return shape needn't be explained, all parameters are fully described in the schema, and annotations carry the safety profile. The description supplies the one non-obvious semantic (same-paper boundary), leaving nothing an agent needs before calling it.

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 all four parameters (ref, lang, window, include_entities) are already documented, including the 1-10 window range and the enum for lang. The description only restates the window concept ('N paragraphs before and after'), adding nothing new about ref formats or entity inclusion, 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 ('Get a paragraph') plus a precise scope modifier ('with surrounding context, N paragraphs before and after within the same paper'). This implicitly differentiates it from the sibling paragraphs.get (single paragraph) and paragraphs.random, though it 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?

'Useful for understanding passages in context' implies the usage scenario but gives no explicit when-to-use/when-not guidance and never points to an alternative such as paragraphs.get. The choice between this and the plain paragraph tool must be inferred.

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 the safety profile is supplied structurally. The description adds behavior beyond that: format auto-detection and the fact that batch refs come back in the same order as the request, plus the 20-item ceiling. It does not discuss return shape, but an output schema exists, so this is a solid rather than exhaustive disclosure.

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

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

Four sentences, front-loaded with the core action, then formats, then batch guidance, then the sibling hand-off. No filler, no restatement of the title, and every sentence carries decision-relevant information.

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?

Six optional parameters and an output schema mean the description needn't enumerate return values, and it correctly focuses on reference handling and batch semantics. The optional enrichment flags (entities, Bible/Urantia parallels) are only covered by the schema, which is acceptable given their self-documenting descriptions, but a single clause on when to enable them would close the last 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 description coverage is 100%, so baseline is 3; the description adds genuine meaning the schema does not, namely that the reference format is auto-detected rather than chosen by the caller, and it clarifies the intended use of `refs` over repeated single calls. It says nothing about `lang`, `include_entities`, or the two parallel-lookup flags, but those are documented in-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 and resource ("look up paragraphs by reference") and immediately enumerates the three accepted reference formats with examples. It also names the sibling tool it is not (paragraphs.context) and the batch sibling behavior, so an agent can distinguish it from paragraphs.context and paragraphs.random 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 is provided: for several paragraphs, pass them all in `refs` in one call (up to 20), and for a passage with its neighbors, use paragraphs.context instead. That covers both the batch alternative and the contextual alternative, leaving little 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety and randomness profile is covered structurally. The description adds the corpus identity and intended-use framing, but says nothing about what the optional enrichment flags do to response size or shape.

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 clauses, purpose front-loaded, no repetition. The second clause is mildly promotional but does carry usable intent signal, so little 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?

Zero required parameters, fully described schema, and an output schema that covers return values. For a simple sampling tool, everything an agent needs to invoke it correctly is present; only sibling routing is unstated, 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 description coverage is 100% — the lang enum, the Spanish CC0 translation caveat, and all three include_* top-10 similarity flags are fully documented in the schema. The description contributes no additional parameter meaning, 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?

Specific verb plus resource ("Get a random paragraph from the Urantia Papers") and the scope is unambiguous. It does not, however, distinguish itself from the adjacent paragraphs.get / paragraphs.context siblings, so an agent must infer that this is the non-deterministic variant.

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 sentence "Great for daily quotes, exploration, or discovering new passages" implies usage contexts but names no alternative and gives no when-not condition (e.g., use paragraphs.get when you need a specific paragraph). Guidance is inferable only.

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, idempotent, non-destructive, closed-world), and the description adds substantial behavioral detail on top: the constraint that the quote must be at least 4 words and lie within one paragraph, plus that case and punctuation are ignored. These are real operational limits an agent must respect, not restatements of the annotations.

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

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

The description is front-loaded with purpose, then return values, then constraints, in compact sentences with no filler. Every clause (verdict values, ignored case/punctuation, 4-word minimum, single-paragraph rule, `ref` behavior) carries information.

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

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

For a 2-parameter verification tool with full schema coverage, annotations, and an output schema, this is complete. Even though the output schema exists, the description usefully previews the verdict taxonomy and match details, leaving nothing an agent needs ambiguous.

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 meaning: it clarifies that `ref` is used to cross-check the reference the quote itself claims, and adds a paragraph-boundary constraint on `text` not captured in the schema. That is genuine added semantic value.

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

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

The description gives a specific verb and resource: it checks whether a quoted passage appears in the Urantia Papers and returns a verdict (exact, close, not_found). This clearly distinguishes it from generic search siblings by framing it as verification rather than retrieval. It stops short of naming a specific alternative tool, so it lands at 4 rather than 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?

Usage is implied by the purpose (use it to verify a quote), and the description explains that passing `ref` also checks the claimed reference. However, it never states when NOT to use it or which sibling (e.g. search.fulltext) to prefer for locating a passage versus confirming one.

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 readOnly/idempotent/non-destructive, yet the description still discloses substantive behavior: the auto-mode fallback ladder (reference → exact phrase → every word → typo fixes → most words) and the set of possible `match` values plus `meta.didYouMean` and `meta.see` signals. That tells an agent how aggressively results were relaxed and how to interpret a partial match.

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?

Purpose is front-loaded in the first clause, followed by mode semantics in a compact two-sentence block; nothing is filler. It is dense with inline code identifiers and quoted examples, which slows scanning slightly for an 11-parameter 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 an output schema present, the description need not enumerate return values, and it covers the hardest part (mode semantics and match relaxation). It is silent on the include_* enrichment flags and the part_id/paper_id filters, but those are self-documenting in the schema and not essential to 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 coverage is 100%, so the baseline is 3; the description earns more by explaining what `type: auto` actually resolves to and by showing that the query accepts structured references ("68:6.3", "103:2", "Paper 68", bare "68") alongside free text. The schema's own mode description is just a bare enum list, so this adds real meaning.

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 ("Keyword search across all paragraphs of the Urantia Papers"), which implicitly separates it from the sibling search.semantic tool. It never names the sibling explicitly, so the keyword-vs-semantic distinction is left to inference.

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 strong guidance on how to pick a mode (auto/and/or/phrase) and what auto does, but says nothing about when to use this tool rather than search.semantic or works.search. Usage relative to alternatives is only implied by the word "keyword".

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 and open-world, so the safety profile is covered. The description adds real behavioral context beyond that: result `strength` (strong/related/weak), `match` (reference/exact/similar), and the fact that the list holds the 100 nearest with meta.total/meta.related counts.

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?

Four dense sentences, front-loaded with the core purpose and the keyword-vs-semantic distinction, then result semantics. No filler, though the strength/match enumeration is slightly compressed and could read as jargon on first pass.

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

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

With a full schema and an output schema present, the description supplies what those don't: input forms and result-label semantics. The only loose end is that the "100 nearest" list is not reconciled with `limit`/`page` pagination, a minor ambiguity.

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% across 10 parameters, so baseline is 3. The description still adds meaning by explaining the two query modes (reference string vs pasted paragraph) that determine how `query` is interpreted, which the schema does not convey.

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 (semantic search over the Urantia Papers via vector embeddings) and immediately differentiates from the keyword-based sibling by noting it returns conceptually related results without exact matches. An agent can distinguish it from search.fulltext 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 concrete usage signals: a reference like "99:1.1" retrieves those paragraphs, and a pasted paragraph returns itself first — useful guidance on accepted query shapes. It stops short of explicitly naming when to prefer search.fulltext over this tool, so it is clear context without full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond them: the response is the *complete* outline ("full", "all 197 papers"), telling the agent there is no filtering, paging, or partial result to work around.

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 action and resource, then the exact returned scope. No filler, no restatement of the title, nothing that fails to earn 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?

An output schema exists, so return-shape explanation is not required, and the single parameter is fully documented in the schema. What is missing is only the connective tissue: no hint about which sibling to call next (papers.get, paragraphs.get) after reading the TOC.

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?

There is one optional parameter (lang) at 100% schema description coverage, including the enum, default, and a note about translation labels, so the schema does the heavy lifting. The description never mentions language selection, adding nothing beyond it; 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 gives a specific verb and resource ("Get the full table of contents of the Urantia Papers") and enumerates scope precisely: Foreword, 4 parts, all 197 papers with titles. That enumeration implicitly separates it from flat listers like papers.list, but no sibling is named, so an agent must infer the boundary rather than being told.

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 explicit when-to-use or when-not-to-use statement, and no alternative tool is named despite a crowded sibling set (papers.list, papers.get, papers.sections, works.list). Usage is only implied: fetch the TOC as a navigation entry point into the corpus.

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 needs no restating. The description adds real domain context the annotations cannot: the corpus is a fixed set of 22 public-domain works sitting beside the Urantia Papers, and `id`/`unitLabel` are described in terms of how they are consumed downstream.

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 tightly packed sentences with no filler; the corpus scope comes first and the field semantics second. The dense set of parentheticals makes it slightly harder to scan than an ideal definition, but 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?

An output schema exists, so return values need not be spelled out, and the description still pre-explains the two fields an agent will act on. It does not mention how to proceed to actual text (works.read) beyond the passing 'other works.* tools' note, which is the only real 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 `lang` parameter — enum, default, and the catalogTranslation caveat — is already fully documented in the schema. The description spends its words on output fields rather than adding meaning to `lang`, 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 names the exact resource — the Bible (WEB) plus 21 public-domain world-religion texts — and explains the two key fields (`id`, `unitLabel`). The verb 'list' lives only in the title; the body implies the catalog rather than stating 'returns the catalog of works'. Still, an agent can distinguish this from works.read and works.search without opening the 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 states that `id` is what the other works.* tools take, which effectively positions this as the discovery step before works.read/works.search. It gives no explicit when-not or comparison to works.search, so it falls short of a full 5.

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, idempotent, non-open-world), and the description adds real behavioral context on top: ordered results, a hard ceiling of 200 units, ranges limited to 50, and the fact that each unit carries its link. It stops short of saying what happens on an unresolvable or overly broad reference.

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 with no filler, and the result shape leads. The opening is a bare noun phrase rather than a verb, which makes it slightly slower to parse as an action statement, but nothing here 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 an output schema present, return values need not be explained, and the description still telegraphs the 200/50 limits and the link-per-unit structure. The lang parameter's catalog-vs-text-language split is left entirely to the schema, and error behavior is unaddressed, keeping it short of full completeness.

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 schema does not: the work prefix is optional ('BG 2.47' equals '2.47'), and Bible references require a book name. That is decision-relevant formatting guidance beyond the property descriptions.

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

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

The description concretely states what comes back: the units of a reference within one work, in order, capped at 200, each paired with its link. That separates it from generic search siblings, but it never names works.search or bible.verse/bible.chapter, so the boundary against them is left implicit.

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 rather than stated: the reader infers this is the direct-lookup path once a work id is known (via works.list) and that 'for the Bible, name the book'. There is no explicit when-to-use-this-instead-of-works.search or bible.verse guidance and no stated preconditions.

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, closed-world search; the description adds real behavior beyond that: the ranking order (reference units, then exact phrase, then every word, then typo correction surfaced in `meta.didYouMean`) and the caveat that attached Urantia paragraphs are semantic parallels, not curated ones.

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-loads scope and the reference-match behavior in the first two sentences, with no filler. The dense backticks and quoted examples are efficient but make it slightly harder to scan than a cleaner layout would.

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

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

With a full input schema, an output schema, and rich annotations, the description still covers ranking semantics, result fields (`match`, `url`, paragraphs), and the semantic-parallel caveat. Nothing an agent needs to call or interpret it 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 description coverage is 100%, so the baseline is 3; the description adds meaning by explaining that `work` narrows to one work and that results carry nearest Urantia paragraphs, tying to `urantia_parallel_limit`. It does not clarify the `q` alias or page/limit behavior 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 and resource ('Keyword search across the Bible and the other works') plus the scoping variant via `work`, which distinguishes it from the semantic siblings. It never names those siblings (works.search.semantic, search.fulltext) explicitly, so differentiation rests on the word 'keyword' 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?

Gives clear usage contexts: pass a reference like 'John 3:16' to get those units first, otherwise it runs phrase then all-words matching, and `work` restricts to a single work. No explicit when-not guidance or pointer to the semantic variants for conceptual queries, so it lacks full routing clarity.

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/openWorld/non-destructive, so the safety profile is covered; the description instead adds behavioral detail the annotations cannot: the result list is capped at 100 nearest chunks, similarity is graded as strong/related/weak, and `meta.total`/`meta.related` measure the list versus the strong matches. The caveat that attached Urantia paragraphs are 'semantic parallels, not curated ones' is a genuinely useful disclosure an agent could otherwise misread as editorial cross-references.

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

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

Three sentences, front-loaded with scope, and every sentence carries information. Slightly over-packed with backticked field names and the 'and ... and ...' chain, but 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?

With an output schema present and full parameter documentation, the description need not restate return values, and it is complete enough on scope and result semantics. The one gap is pagination: it says the list holds 100 nearest chunks while the schema exposes `page` and a default `limit` of 20, leaving the total-versus-page relationship mildly ambiguous.

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 schema already explains `work`, `limit`, `page`, and `urantia_parallel_limit`. The description reinforces `work` scoping and implies the Urantia-paragraph attachment (urantia_parallel_limit), but adds no syntax or interaction detail (e.g., paging versus the 100-chunk cap) 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+resource (natural-language/semantic search over the Bible and other works) plus the scoping option via `work`. An agent can tell it is the semantic variant rather than keyword search, though it never names the sibling it supersedes (works.search, bible.search.semantic) to make the distinction airtight.

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: 'across the Bible and the other works, or one work with `work`' tells the agent it may scope results, but there is no explicit when-to-use versus works.search or bible.search.semantic, and no prerequisites or exclusions. Adequate but leaves selection between siblings 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: exactly 10 results, ranked by semantic closeness, and that these are computed similarities rather than curated equivalences. It stops short of describing ordering/scoring output or whether results can be 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?

Three short sentences, front-loaded with what is returned and how many. The middle caveat earns its place; the trailing 'The reference must name one unit' is slightly redundant with the schema's examples but is short enough not to be 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a fixed-size, two-parameter read tool the description is nearly sufficient; the one gap is the missing sibling differentiation against bible.verse.urantia_parallels, which an agent choosing between them would want.

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

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

Schema coverage is 100% and both parameters carry examples ('John 3:16', 'bhagavad-gita'), so the schema already does the heavy lifting. The description adds only the constraint that the reference must name one unit, which slightly narrows the schema's stated allowance of 'a short range, or a chapter'. 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: the 10 Urantia paragraphs semantically closest to one unit of a named work. The parenthetical '(the chunk that holds it)' clarifies what a unit is. It does not name the near-identical sibling bible.verse.urantia_parallels or explain how it differs, so an agent must infer the distinction.

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 line 'Semantic parallels, not curated ones: they do not claim that two teachings are the same' sets expectations for interpreting results, and 'The reference must name one unit' is a usage constraint. But there is no explicit when-to-use guidance, and no pointer to bible.verse.urantia_parallels (which presumably serves the same role for Bible verses) or works.search.semantic as alternatives.

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