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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing the safety profile. The description adds valuable behavioral details about input normalization: accepted OSIS/USFM codes, full names, aliases, case-insensitivity, and tolerance for hyphens/underscores. This goes beyond the structured annotations and helps agents invoke the tool correctly. No contradiction found.

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

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

The description is two sentences: the first states the core purpose, the second elaborates on accepted input formats. Every word earns its place, with no redundant filler. It is front-loaded with the most important 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?

Given the tool's simplicity (one parameter), the rich annotations, and the presence of an output schema, the description covers all necessary context. It transparently explains input flexibility and what the metadata contains, while the output schema handles return-value documentation. No critical gaps remain.

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 already documents the single required parameter 'book_code' with examples. The description enriches this by enumerating accepted formats (OSIS, USFM, full names, aliases) and explicit normalization rules (case-insensitive, hyphen/underscore tolerance). This adds meaning beyond the schema's basic example list, raising it above the baseline of 3.

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 metadata for a single Bible book including chapter and verse counts.' This specific verb+resource combination distinguishes it from siblings like bible.books (list) and bible.chapter (chapter content). The distinction is further reinforced by the words 'single 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 provides clear context for when to use this tool: when you need metadata for one specific Bible book. It does not explicitly name alternatives or exclusions, but the scope is unambiguous enough for an agent to infer appropriate usage. It falls short of a 5 because it does not mention alternative tools for related tasks.

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 indicate read-only and idempotent behavior. The description adds valuable context by specifying the translation (eng-web), canon breakdown, and per-entry fields, which goes beyond the annotation. No behavioral surprises are introduced.

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 concise sentences with the key information upfront. It avoids redundancy and every sentence contributes meaningful detail about the output contents.

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 simple nature (0 params, output schema present), the description fully covers what the tool returns and its scope. It mentions all entry fields and the exact book count, leaving little ambiguity for an agent.

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 parameters, the baseline is 4. The description does not need to explain parameter semantics, and it adds no irrelevant parameter information.

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 action ('List') and resource ('all 81 books of the World English Bible'), including specific counts and fields. This distinguishes it from siblings like bible.book or bible.chapter that likely handle individual items.

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 'List all 81 books' makes the scope obvious, so an agent knows this is for obtaining the full list rather than a specific book. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a 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?

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds real context beyond annotations: results are cosine-ranked, each carries top-N pre-computed Urantia parallels, and `urantia_parallel_limit=0` suppresses them. It omits pagination/default behavior, but the schema carries that.

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 the core capability, then the enrichment feature, then filters and the disable switch. Five tight sentences, though the Urantia-parallel point is stated twice ('One query surfaces both...' plus the limit note), which is mildly redundant.

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

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

With annotations covering safety and an output schema covering the result shape, the description supplies the remaining essentials: ranking method, enrichment behavior, and filter/disable switches. Pagination and default limits are left entirely to the schema, which is acceptable given its coverage.

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 is already documented. The description restates the filter values and the '0 disables' behavior the schema already states, adding no new parameter semantics; 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 ('free-form natural-language search across all Bible chunks') plus the ranking mechanism (cosine similarity) and the merged Urantia-paragraph enrichment. The Bible-only scope plus the dual-surface behavior distinguishes it from the general `search.semantic` sibling without needing to name it.

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 search,' and the description usefully notes the dual Bible+Urantia surface. However, it never states when to prefer this over keyword search (`search.fulltext`) or over the structured `bible.verse`/`bible.chapter` tools, nor 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 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description's help. The description's contribution is the return-field inventory (name, type, aliases, description, related entities, citation count), which is useful but does not disclose anything beyond what the output schema covers.

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 written sentences: the lookup operation is front-loaded, and the return summary follows with no filler. 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 one fully documented parameter, a complete set of annotations, and an output schema present, the description needs only to state the operation and its target. It does exactly that and nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% with a single, fully documented required parameter whose example is already in the schema. The description adds only 'by its slug ID', which restates the schema's own description rather than extending it, 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 a specific verb ('Get') and resource ('a specific entity by its slug ID'), and enumerates the returned fields, so an agent knows exactly what this tool produces. It does not explicitly name a sibling to differentiate from (e.g., entities.list, entities.paragraphs), so it stops 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?

Usage is only implied by the word 'specific entity' -- the agent can infer this is the single-record lookup versus entities.list. There is no explicit when-to-use statement, no exclusion, and no pointer to a sibling alternative, so it lands at minimum-viable.

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 only domain framing (Urantia Papers, entity types) and says nothing about pagination behavior or result volume beyond what annotations/schema 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?

Two tightly written sentences with no padding; the catalog contents are front-loaded so an agent immediately knows the scope. Slight deduction only because the second sentence reads as a capability list rather than actionable guidance.

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 list tool with an output schema and 100% schema coverage, the description conveys purpose and domain scope adequately. The only real gap is routing to/from the sibling entities.get, which is a minor omission given annotations already cover behavior.

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 all five parameters (q, page, type, limit, query) are already documented in the schema. The description mentions filtering by type and searching by name but adds no syntax, format, or alias detail, so the baseline 3 applies.

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

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

States a specific verb ('Browse') and resource ('entity catalog') and enumerates the concrete entity types (beings, places, orders, races, religions, concepts). However, it never names the sibling entities.get or contrasts listing against fetching a single entity, so differentiation 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 second sentence ('Supports filtering by type and searching by name') implies when the tool is useful, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the alternative entities.get for single-entity lookups.

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). The description adds a real behavioral trait not in the annotations: results are 'ordered by position in the text,' which tells the agent how output is sequenced.

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

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

Two sentences, front-loaded with the core action before the use-case rationale. Both sentences carry weight, though the second is somewhat soft framing rather than essential 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?

With rich annotations, a fully documented schema, and an output schema, the description needn't explain return values. It covers purpose, ordering, and a use case; only explicit sibling routing 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% and all three parameters (entity_id, page, limit) are documented in the schema with defaults and bounds. The description adds no parameter syntax or format detail beyond the schema, 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 with scope: 'Get all paragraphs that mention a specific entity.' This distinguishes it from paragraphs.get (single paragraph) and entities.get (the entity itself). It does not, however, explicitly name a sibling to route against.

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 studying everything said about a particular being, place, or concept' gives a use case but no when-to-use/when-not guidance and no comparison to alternatives like search.fulltext or paragraphs.context. Usage is implied rather than directed.

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 bar is lower. The description still adds real context beyond them: the exact cardinality (197) and the fact that the result is a complete, unpaginated flat list rather than a nested tree.

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

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

A single sentence that front-loads the verb and scope, then names the payload fields. Every clause earns its place with no preamble or filler.

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

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

An output schema exists, so return-shape explanation is not required, yet the description still names the key fields. For a no-arg enumeration tool with full annotation coverage, nothing an agent needs before calling 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Schema coverage is 100% and there is nothing for the description to compensate for.

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'), resource ('papers'), scope ('all 197'), and returned fields (id, title, partId, labels). The contrast with the singular sibling papers.get is implicit in 'all ... as a flat list' rather than explicitly named, so it stops short of the top band.

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: enumerate the complete paper set when you need the whole catalog rather than one paper. No explicit when-to-use, when-not-to-use, or named alternative (e.g. papers.get, papers.sections) is given, so it is only the minimum viable level.

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 indicate a safe, idempotent read operation. The description adds useful behavioral details beyond annotations: 'all sections' and 'ordered by section number.'

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

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

The description is two succinct sentences with the verb front-loaded. No unnecessary 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?

The description is sufficient for a simple read-only tool with one parameter and an output schema. However, it does not clarify the relationship to the sibling tool toc.get, which could cause ambiguity in tool selection.

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 fully describes the single paper_id parameter with type, description, and example, so the description does not need to add much. The phrase 'within a paper' reinforces the parameter's role but adds no new technical detail.

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 'Get all sections within a paper, ordered by section number', using a specific verb and resource. It distinguishes from papers.get and papers.list, but does not explicitly differentiate from the similarly named toc.get.

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 a clear use case: 'Useful for understanding paper structure before reading specific sections.' It implies when to use the tool but does not mention alternatives or 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral constraint not in the schema: context retrieval is bounded to the same paper and never crosses document boundaries. It says nothing about ordering of returned paragraphs or how the target is delimited within the window.

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 is returned and immediately qualified by the scope constraint. The trailing rationale sentence earns a little place but is close to 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 values need not be explained, and annotations carry the safety profile. The remaining gap is sibling differentiation against paragraphs.get and entities.paragraphs, which would help an agent choose 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%, so the schema already documents ref, window (1-10, default 2) and include_entities. The description only restates the window behavior ('N paragraphs before and after') with no additional format or semantics, 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 ('Get') and resource ('a paragraph') plus the defining scope modifier ('with surrounding context ... within the same paper'). An agent understands exactly what it returns. It does not, however, distinguish itself from the sibling 'paragraphs.get', which an agent could easily confuse with this tool.

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

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

'Useful for understanding passages in context' implies the usage scenario (contextual reading) but gives no explicit when-to-use vs paragraphs.get, no exclusions, and no mention of alternatives. Usage is inferable but 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 the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that the reference format is auto-detected — but says nothing about error behavior for invalid refs or what happens when a parallel flag finds no matches.

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 the core action followed by the format detail. No filler 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 a full output schema present, return values need not be described, and annotations carry the safety profile. The definition is nearly complete for a single-lookup tool; only the routing versus sibling paragraph tools is unaddressed.

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 are already documented, including the three include_* flags. The description's format enumeration largely repeats the schema's ref examples rather than adding new semantics, 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+resource ('Look up a specific paragraph by reference') and clarifies the accepted reference formats. It does not differentiate itself from near-siblings like paragraphs.context or paragraphs.random, but the core purpose is 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?

Usage is implied by the verb and the format list, but there is no explicit when-to-use guidance and no mention of alternatives such as paragraphs.context (surrounding paragraphs) or paragraphs.random. The agent must infer which tool to pick.

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=true and destructive=false, lowering the burden. The description's 'random' wording aligns with idempotentHint=false, but it never explicitly warns that repeated calls return different paragraphs, and it omits that the three include_* flags add extra derived content to the response.

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. The second sentence is somewhat promotional but does convey intended use cases, so it mostly 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?

An output schema exists, so return values need no explanation, and all parameters are documented in the schema. Safety is covered by annotations; only the non-idempotent/random-repeat behavior is left implicit.

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

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

All three boolean parameters are fully documented in the schema (100% coverage), so a baseline of 3 is correct. The description adds no parameter-level meaning beyond what the schema already supplies.

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

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

States a concrete verb (Get), resource (paragraph), and a specific qualifier (random from the Urantia Papers). The 'random' qualifier implicitly distinguishes it from paragraphs.get (targeted retrieval by ID) and paragraphs.context, so an agent can pick 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?

'Great for daily quotes, exploration, or discovering new passages' gives use-case flavor but never states when to choose this over paragraphs.get or search.semantic, nor any precondition. Usage is implied rather than defined.

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 behavior beyond that: the mode semantics (all/any/exact) and that results are ranked by relevance, which is useful context the annotations do not carry.

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

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

Three tight sentences: scope first, then modes with the default called out, then ranking behavior. No filler and everything 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?

With a full output schema, return values need no explanation, and annotations cover safety. The description covers scope, modes, and ranking adequately for a 10-parameter search tool, though it never touches the filter or include_* flags that materially change results.

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

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

Schema description coverage is 100% across all 10 parameters, so the schema already documents q/query aliasing, pagination, filters, and the include_* flags. The description only echoes the type enum values, adding little beyond what the schema provides; 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+resource (full-text search across all paragraphs of the Urantia Papers), which is clear and concrete. However, it does not differentiate from the sibling search.semantic, leaving the agent to infer which search to pick.

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 explains the three modes and marks 'and' as the default, which is implied usage guidance for mode selection. But there is no when-to-use vs when-not guidance, and notably no routing advice against the sibling search.semantic tool.

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 and destructiveHint=false, so the safety profile is covered. The description adds the behavioral note that semantic matching can return results with no literal term overlap, but says nothing about pagination defaults, result volume, or cost/latency of embedding search.

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 purpose, no filler. It is efficient, though notably terse given a nine-parameter tool with rich optional enrichment flags.

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 and full annotations exist, so return values and safety need no explanation here. However, with zero required parameters yet a query string effectively needed to get results, and with two overlapping query parameters (q vs. query), the description does nothing to head off an empty or ambiguous call.

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

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

Schema description coverage is 100%, so all nine parameters (including the q/query alias, filters such as paper_id/part_id, and the include_* enrichment flags) are already documented in the schema. The description adds no parameter-level meaning, 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 ('Search the Urantia Papers') plus the mechanism ('semantic similarity (vector embeddings)'), which implicitly distinguishes it from the keyword-based sibling search.fulltext and from bible.search.semantic's different corpus. An agent can tell what it does and why it differs from full-text 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?

The clause 'Returns conceptually related results even without exact keyword matches' implies when this tool beats a keyword search, but the description never names search.fulltext or search.semantic alternatives, states no exclusions, and gives no guidance on the optional filters or parallel-enrichment flags. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds scope context (whole-document TOC) but no behavioral traits beyond that, and with an output schema present the return shape is already documented elsewhere.

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 purpose and followed by the concrete return contents. Every clause earns its place with no filler or repetition 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 zero-parameter, read-only lookup with an output schema and full annotation coverage, the description supplies everything needed to invoke it correctly. The only missing element is guidance on choosing it over sibling retrieval 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. No misleading parameter hints are given.

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 (Get) and resource (table of contents of the Urantia Papers) and enumerates the exact returned structure — Foreword, 4 parts, all 197 papers with titles. That enumeration distinguishes it from the sibling papers.list, which returns paper-level data rather than the whole TOC.

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: the phrase 'full table of contents' suggests a top-level navigation call, but there is no explicit when-to-use, when-not-to-use, or reference to an alternative such as papers.list. For a zero-parameter tool the intent is largely self-evident, so a 3 is fair.

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