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?

With annotations already declaring readOnly/idempotent/non-destructive, the description adds valuable context: cosine similarity ranking, pre-computed UB parallels with a direction, the ability to suppress them via urantia_parallel_limit, and the OPENAI_API_KEY dependency. This goes well beyond the annotation safety profile and discloses practical operational details.

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, front-loaded with the core purpose, followed by the key behavioral details and filters. Every sentence earns its place, with no fluff 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?

Given a rich schema, annotations, and an existing output schema, the description sufficiently covers the tool's core function, result composition, filtering options, dependency requirement, and a way to suppress the UB attachment. It is complete for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, and every parameter already includes a description. The tool description adds some context around filter meanings and the urantia_parallel_limit effect, but it mostly repeats what the schema already provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb+resource+approach: 'Free-form natural-language search across all Bible chunks, ranked by cosine similarity.' It clearly distinguishes from sibling tools like search.fulltext and search.semantic by emphasizing the Bible scope and the UB parallel attachment with direction=bible_to_ub.

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 conveys the use case: natural-language semantic search over Bible content with optional canon/book filters and UB parallel enrichment. It implies when to use (semantic instead of keyword) and mentions the API key prerequisite, but it does not explicitly name alternatives or state when not to use this 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, 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?

Beyond the read-only and idempotent annotations, the description discloses pre-computation with text-embedding-3-large, cosine similarity, and the output's similarity score and rank. It also transparently warns that results are semantic, not curated, and should be treated as starting points—all valuable behavioral context.

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 concise and front-loaded with the core purpose, followed by technical details and a caveat. Each sentence adds distinct value—purpose, method, output format, and usage caution—without any wasteful 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?

Given the tool's moderate complexity, the description comprehensively covers what it does, how it works, what the output includes, and how to interpret results. An output schema exists, so return structure is further specified, and the description complements the schema effectively.

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 parameters are already documented. The tool description does not add any parameter-level detail beyond the schema, and the parameters (book_code, chapter, verse) are self-explanatory. Thus, 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?

The description clearly states the tool returns the top 10 Urantia paragraphs semantically nearest to a Bible verse's chunk, using a specific verb and resource. It also distinguishes itself by noting it is the reverse of the UB-side `include_bible_parallels` tool, which differentiates it from siblings like `bible.verse` or `search.semantic`.

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 by explaining this is the reverse direction of `include_bible_parallels`, implying when to use this tool (from Bible side to Urantia) versus the alternative. However, it does not explicitly list exclusions or name siblings in a direct 'use X instead' manner, so it falls short of the highest bar.

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 clear. The description adds the list of returned fields, but since an output schema exists, this is redundant. No additional behavioral traits (e.g., rate limits, auth, error handling) are mentioned, but none are critical for a simple read operation.

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

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

The description is a single, well-structured sentence that front-loads the action and quickly conveys purpose and output. Every word contributes value with no 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?

For a simple read-only get tool with one parameter and an output schema, the description is complete enough. It states the input identifier and summarizes the returned fields. It does not mention what happens when the entity is not found, but this is a minor gap given the simplicity and the presence of an 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% for the single parameter entity_id, including an example. The description merely reiterates 'slug ID' without adding new meaning, so it meets the baseline but does not exceed it.

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 action ('Get'), the resource ('entity'), and the scope ('by its slug ID'), while also listing the key fields returned. This distinguishes it from sibling tools like entities.list and other getters such as papers.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 implies the usage context: use when you need detailed information about a specific entity identified by slug. It does not explicitly state when not to use or mention alternatives, but the scope is clear enough for an agent to select this tool over list or search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context by specifying the catalog scope ('beings, places, orders, races, religions, and concepts mentioned in the Urantia Book') and the supported operations (filter by type, search by name), which go beyond the structured metadata.

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, front-loaded with the primary purpose, and contains no filler or redundant restatement of the tool name. Every word contributes to understanding what the tool does.

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 rich annotations, 100% schema coverage, and presence of an output schema, the description provides sufficient context. It explains the catalog scope, supported filtering/searching behavior, and is fully adequate for an AI agent to select and invoke the tool correctly without missing information.

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 reinforces the meaning of the 'type' and 'query' parameters by stating 'filtering by type and searching by name', but it does not add meaningful detail about page, limit, or the q alias that is not already present in 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 uses a specific verb ('Browse') and resource ('entity catalog'), and explicitly enumerates the entity categories it covers. It clearly distinguishes this listing tool from sibling tools like entities.get by framing it as catalog browsing rather than fetching a specific entity.

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 implies when to use this tool: to browse or explore entities in the catalog, with filtering by type and searching by name. It does not explicitly mention entities.get as the alternative for retrieving a single entity, but the context is clear enough that no exclusions are needed.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results are ordered by position and scoped to entity mentions, which is useful beyond the annotations. No contradiction exists.

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

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

Two concise sentences: the first gives the verb, resource, and scope/ordering; the second adds a usage context. No redundant 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 output schema and annotations present, the description suffices for selection and invocation. The phrase 'all paragraphs' is slightly ambiguous given pagination, but the schema's page/limit fields clarify that.

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 parameters have schema descriptions (100% coverage), including entity_id with an example. The description does not add meaning 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?

The description clearly states the tool retrieves paragraphs mentioning a specific entity, with a specific ordering. This distinguishes it from sibling tools like entities.get (entity metadata) or paragraphs.get (specific paragraph lookup).

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 a clear use case ('studying everything said about a particular being, place, or concept') and implies when to use it, but does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds the ID range and optional entity mentions. However, these are largely restatements of schema properties rather than new behavioral traits like rate limits or error handling. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose. Everything included is relevant: the resource, the ID range, and the optional parameter. 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?

For a simple read tool with an output schema, full parameter coverage, and safe annotations, the description is complete. It tells the agent what the tool returns (a paper with all paragraphs), the valid ID range, and the optional include_entities flag. Sibling tools are distinguishable.

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 have clear descriptions. The description's mention of ID range and optional entity mentions mirrors the schema, adding no new meaning beyond what the structured schema already provides.

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

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

The description opens with a specific verb and resource: "Get a single paper with all its paragraphs." It clearly distinguishes from siblings by emphasizing "single paper" and all paragraphs, which contrasts with papers.list (list) and papers.sections (sections).

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 when you need a specific paper, but does not explicitly state when to prefer this tool over papers.list, papers.sections, or entities.get. The ID range provides operational context but no explicit comparison to alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context by specifying the fixed count (197), the metadata fields returned, and the fact that it returns 'all' papers, which goes beyond annotation data without contradicting it.

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

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

The description is perfectly concise: two short sentences, the first stating the action and result, the second pointing to an alternative. No wasted words, and the key information is front-loaded.

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

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

The tool is simple (no parameters), has full annotations and an output schema. The description covers the essential behavioral context: what it lists, what fields are included, and how it differs from toc.get. There is no missing information that would hinder correct selection or 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?

The tool has zero parameters, so schema coverage is 100% by default. The description adds meaning by listing the metadata fields (id, title, partId, labels) that will appear in the output, giving the agent a preview of the result structure without needing parameters.

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 lists all 197 papers in the Urantia Book with specified metadata fields (id, title, partId, labels). It uses a specific verb 'list' and explicitly distinguishes itself from toc.get, which provides a hierarchical view.

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

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

The description provides explicit guidance: 'Use toc.get for a hierarchical view instead.' This tells the agent when to use this tool (flat list) versus an alternative, effectively communicating the use case.

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=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the same-paper scoping constraint and the configurable window size, but does not discuss boundary behavior or return structure. With annotations covering safety, this is adequate but not rich.

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 concise sentences: the first states the core function and key constraint, the second provides a usage hint. 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?

The tool is simple (3 params, 1 required), has an output schema, and annotations. The description covers the core purpose and window behavior. It doesn't explain edge cases like boundaries, but given the output schema and low complexity, the description is adequately complete.

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

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

Schema description coverage is 100%, and each parameter has clear text in the schema (e.g., window described as 'Number of paragraphs before and after'). The description adds minimal extra meaning beyond what the schema already provides, which meets the baseline for high 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 gets a paragraph along with a configurable window of surrounding paragraphs within the same paper. The verb 'Get' and resource 'paragraph with surrounding context' are specific and the scope 'within the same paper' distinguishes it from sibling tools like paragraphs.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 indicates usefulness 'for understanding passages in context,' providing a clear usage context. It does not explicitly name alternatives or state when not to use, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds non-obvious behavioral context: that the reference format is auto-detected, which helps the agent understand input flexibility without additional calls. It does not describe error handling for invalid references, but the annotation coverage lowers the bar, and this added detail is valuable.

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, front-loaded with the primary action, and provides essential format details without redundancy. Every word earns its place, and the structure is clean.

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

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

Given the tool has an output schema and 100% schema coverage, the description needn't explain return values or every parameter. It covers the core purpose, the input format nuance (auto-detection), and the single-paragraph scope. It could mention when not to use it (e.g., for context or random access), but overall it is sufficiently complete for a simple lookup tool with strong schema and annotations.

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 beyond the schema by naming the three formats (globalId, standardReferenceId, paperSectionParagraphId) and explicitly stating auto-detection, which clarifies how the 'ref' parameter should be interpreted. This goes beyond simply restating schema info.

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

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

The description uses a specific verb ('look up') and resource ('paragraph by reference'), clearly distinguishing it from sibling tools like paragraphs.random or paragraphs.context. The mention of 'specific paragraph' and the three reference formats leaves no doubt about what the tool does.

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 states the context of use ('specific paragraph by reference') which implies it is for targeted lookup, not random or contextual retrieval. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to choose this tool when a reference is available.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing it as a safe read operation. The description adds behavioral context by highlighting its random nature, indicating that results will vary on each call, which aligns with idempotentHint=false. It also suggests typical use cases. This adds value beyond the structured data 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 two sentences long, front-loading the core purpose in the first sentence and adding use-case context in the second. Every word earns its place—no redundancy, fluff, or restatement of the name. It is concise and well-structured.

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

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

For a simple random-access tool with three optional boolean parameters and an output schema, the description is sufficient. It explains the core function and typical use cases. Parameter details are fully covered by the input schema, and the output schema handles return value descriptions. There are no hidden complexities or missing prerequisites that need to be disclosed.

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 tool description does not mention or elaborate on the parameters (include_entities, include_bible_parallels, include_urantia_parallels), leaving their semantics entirely to the schema. Since the schema already provides thorough descriptions, the tool description adds no additional parameter meaning, so a 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?

The description clearly states the tool's function: 'Get a random paragraph from the Urantia Book.' It uses a specific verb ('Get'), identifies the resource ('random paragraph from the Urantia Book'), and distinguishes it from sibling tools like paragraphs.get (which retrieves specific paragraphs) and paragraphs.context (which provides surrounding context). The random aspect is explicit.

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 usage context: 'Great for daily quotes, exploration, or discovering new passages.' It implies when to use this tool (for casual discovery) but does not explicitly mention alternatives or exclusions, such as 'use paragraphs.get for a specific paragraph.' Since it gives context but not explicit when-not-to-use guidance, it merits a 4.

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 read-only annotations, the description explains the behavioral differences between 'and', 'or', and 'phrase' modes and states that results are ranked by relevance. This adds useful context about search semantics and result ordering.

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

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

Two sentences with no fluff. The description leads with the tool's purpose, then covers modes and result ranking, earning every word.

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 complete for a search tool: scope, modes, and ranking are specified. Optional filters (part_id, paper_id, include_* flags) are documented in the schema, and the output schema exists, so the description does not need to repeat them. It does not mention pagination behavior, but the page and limit parameters cover that.

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 all 10 parameters at 100% coverage. The description adds meaning by explicitly defining the 'type' parameter's modes ('and' = all words, 'or' = any word, 'phrase' = exact phrase), which the schema only labels as 'Search mode'. This extra semantic value elevates it above the baseline.

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 performs full-text search across all Urantia Book paragraphs and lists three search modes. It does not explicitly distinguish itself from sibling search.semantic, so it misses the top score.

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 keyword-based search with exact-phrase or word-matching semantics, which differentiates it from semantic search. However, it does not explicitly instruct when to use this tool versus alternatives like search.semantic.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds a critical operational dependency: 'Requires OPENAI_API_KEY'. It also clarifies the underlying technique (vector embeddings), which is behaviorally relevant, compensating for the lack of error/rate-limit details.

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 and method, the second adds the key dependency and a differentiating attribute. No filler words or redundant restatements.

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 rich annotations, full schema coverage, and an output schema, the description covers essential operational context (read-only conceptual search, API key requirement). It doesn't discuss pagination or filters, but those are fully specified in the schema, so the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all 9 parameters documented including defaults, ranges, and examples. The description adds no parameter-specific details beyond the schema, 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 states 'Search the Urantia Book using semantic similarity (vector embeddings)' with a specific verb, resource, and method. It also distinguishes from exact keyword search by noting it returns results 'even without exact keyword matches', which separates it from sibling search.fulltext.

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 conceptual queries rather than exact-match search via 'even without exact keyword matches'. However, it does not explicitly name an alternative like search.fulltext or state when not to use the tool, so it stops short of full exclusion 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, and non-destructive behavior. The description adds context about the exact content ('Returns all 4 parts and 197 papers with their titles') and its purpose as a starting point. This is valuable but does not contradict or require additional safety disclosures.

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 effectively convey the purpose, content, and usage context. No wasted words, key information is front-loaded.

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

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

Given the tool has no parameters and an output schema exists, the description sufficiently explains what it returns and why it is useful. It is complete for a simple read-only TOC retrieval 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 tool has zero parameters, so schema coverage is trivially 100%. The description needs to explain no parameters, and it does not. Baseline for 0 params is 4, and there is no missing parameter information 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?

The description clearly states the tool gets the full table of contents of the Urantia Book, specifying it returns all 4 parts and 197 papers with titles. This distinguishes it from sibling tools like papers.list or bible.books by focusing on the complete structural overview.

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 provides clear context by saying 'This is the best starting point to understand the book structure,' implying when to use it for overview purposes. However, it does not explicitly mention when not to use it or alternatives like papers.list or bible.books, so it lacks the explicit exclusions of a 5.

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