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

The description adds behavioral details beyond annotations and schema: the root must be normalized, the search uses an inverted root index, and results are paginated. These are meaningful characteristics that affect how the agent invokes the tool, while remaining consistent with the readOnlyHint and idempotentHint 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 short sentences that front-load the main action and convey the essential normalization requirement and pagination behavior. No superfluous words.

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, paginated search tool with annotations covering safety and a clear resource ('verses'), the description sufficiently conveys the purpose and key behavioral notes. It lacks an explicit return structure, but 'Find verses' adequately implies the result type. It could mention alternatives for full completeness, but the simplicity of the tool makes this adequate.

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

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

The schema has 0% description coverage, so the description carries the burden. It clarifies that the 'root' parameter expects a normalized Arabic root and that pagination applies to the 'page' and 'limit' parameters, but it does not elaborate on each parameter's precise role or constraints beyond what the 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 clearly states the tool finds verses containing a normalized Arabic root using an inverted root index, distinguishing it from sibling tools like find_verses_by_lemma (root vs lemma) and get_verse (single verse). The verb 'find' and resource 'verses' are specific and unambiguous.

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

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

The description implies usage for root-based verse queries but does not explicitly state when to use this tool over alternatives such as find_verses_by_lemma or search. There is no mention of exclusions or when-not-to-use guidance, leaving the decision to inference from the tool name and context.

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