graph_enriched_search

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 useful scope behavior beyond the annotations: verse-level granularity only, and that entity lists come with relationships and verse text. It stops short of return-shape, pagination, or failure behavior, so it is strong but not exhaustive.

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 purpose and ends with the sibling differentiation, which is the highest-value sentence. The first line and second paragraph overlap ('its text plus all people, places, events, and family relationships' vs 'Returns the verse text, the people, places, and events'), costing some redundancy, but nothing is off-topic.

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?

No output schema exists, so the description must explain returns — and it does, listing verse text, people, places, events, and family relationships. Combined with the sibling routing, an agent has everything needed to call it correctly.

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

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

One required parameter with 100% schema description coverage, so the schema already documents the reference format. The description only reinforces this with the 'Matthew 1:1' example, adding no syntax beyond the schema. Baseline 3 applies when the schema carries the parameter semantics.

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 (retrieve) and resource (enriched view of a single verse) and enumerates exactly what is returned: verse text, people, places, events, family relationships. It explicitly distinguishes itself from lookup_verse and people_in_passage, so the agent can pick it without reading sibling schemas.

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?

Names both alternatives and the conditions that separate them: it 'combines what lookup_verse and people_in_passage return separately,' and it is 'verse level only' whereas people_in_passage also takes chapters and omits verse text/relationships. When-to-use and when-not-to-use are both explicit.

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