search_hadith

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds one genuine behavioral fact beyond annotations: results must contain every word of the query (AND semantics, not fuzzy/OR matching). It says nothing about pagination, result ordering, or default scope, so this is adequate but thin against a lowered annotation bar.

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?

A single short sentence with no padding and the core matching semantics front-loaded, which is efficient. But the brevity is under-specification rather than disciplined conciseness, since none of the four parameters or the search scope is covered.

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?

An output schema exists, so return values need not be described. The gaps are on the input side: four undocumented parameters with non-obvious defaults, no language/collection value hints, and no indication of how matching behaves across languages. For a 4-parameter search tool this leaves the agent under-equipped.

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% across four parameters, so the description carries the full burden and largely fails: 'collection' is mentioned only in passing, and limit, language, and the default values (language='fra', collection='bukhari', limit=10) are never explained. An agent has no textual basis for choosing valid language or collection values.

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 identifies the resource (hadiths) and implies a search operation via 'containing every word of the query', which conveys AND-matching semantics. However, no verb is stated and it never distinguishes itself from siblings like search_quran or get_hadith, so the agent must infer that this is the keyword-search entry point.

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?

There is no guidance on when to use this tool versus search_quran (scripture corpus) or get_hadith (single-record retrieval), nor any prerequisite or exclusion. The agent must infer usage purely from the corpus name.

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