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

With no annotations provided, the description carries the full burden. It explains the embedding mechanism, optional hybrid fusion, and how the tool differs from keyword matching. However, it doesn't disclose return format details, pagination, or performance implications of hybrid mode despite an output schema existing. The behavioral description is adequate for what it covers but omits some relevant traits like result ordering or limits.

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 compact and information-dense in three sentences. It includes examples, the full scope, and optional parameter meanings. Slightly dense single-flow paragraph could benefit from bullet separation, but each sentence earns its place 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?

Given the tool's moderate complexity (4 params, output schema present, no nested objects), the description covers the core search semantics, scope, examples, and two of four parameters. The presence of an output schema covers return-shape concerns. The main gap is the undocumented 'top_k' parameter and no guidance on query formulation best practices. Reasonably complete for the complexity level.

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 0%, so the description must compensate. It does explain 'kind' ('verse | window | paragraph') and 'hybrid' (fused with keyword search, recommended). However, 'query' and 'top_k' are not described — top_k's default of 12 and its meaning as a result-count limit are left entirely to the schema. The description partially compensates for the zero schema coverage but misses two of four 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 'Meaning-based search across the whole corpus — scripture AND prose works — using embeddings'. It uses a specific verb (search), identifies the resources (whole corpus), and explains the distinctive capability (finds passages about a theme even with no shared words). This distinguishes it well from siblings like 'search' (keyword-based) and 'find_similar'.

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 specifies the scope (whole corpus), the optional hybrid mode ('optionally fused with keyword search', 'recommended'), and gives concrete examples ('divine self-emptying', 'the soul's dark night'). While it doesn't explicitly state when NOT to use it or name alternatives, the contrast with keyword search is implicit. It clearly conveys when semantic search is appropriate but lacks an explicit exclusion of alternative tools.

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