Get a passage

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

Beyond the readOnly/idempotent annotations, the description adds genuinely useful behavior: text is the Berean Standard Bible, sixteen verses intentionally return empty text but keep their verse numbers, and the returned context includes speakers, places, people, themes, cross references, and back-references. This explains quirks an agent would otherwise discover by failure.

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

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

The description is front-loaded with the primary action and examples, then expands into context and version-specific edge cases. Every sentence adds operational information, and the special empty-verse behavior is placed where it is easy to discover.

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 one required parameter, with output schema present and safe/idempotent annotations, this description is complete. It specifies what output to expect, spelling, edition, and edge cases. An agent can confidently decide when to use it and know what kind of data will come back.

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 single parameter is fully documented in the schema, but the description adds practical syntax guidance: "John.3.16", "John.3.16-18", and "John.3" show chapter and range forms, not just a single verse. This is more useful than the schema description alone.

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?

"Fetch a verse, a verse range or a whole chapter by OSIS reference" names a specific verb, a clear resource, and the exact input format. It also describes what the result contains (speakers, people, places, themes, cross references), which separates this citation-driven tool from sibling tools like search or find_cross_references.

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

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

The description gives strong context for when to use it: when you have an OSIS reference and want the topical context around a passage, calling it "the main way into the topical side of the knowledge base." It does not explicitly list excluding alternatives, such as 'use search_scripture when you only have words', but the intended use is clear.

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