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

L'annotation readOnlyHint=true couvre déjà la sécurité, et la description ajoute des comportements essentiels : recherche par lemme, traduction automatique des autres langues, OCR fautif et non vocalisé. Elle prévient que les extraits servent à localiser un passage et non à citer, ce qui évite des attentes erronées.

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?

La description est dense et front-loadée : l'information clé sur la recherche plein texte apparaît dès la première phrase. On note une légère redondance entre « Recherche PLEIN TEXTE » et « Cherche dans le contenu des livres, pas seulement les titres », mais chaque phrase apporte soit un cas d'usage, soit une limitation utile.

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?

Il n'y a pas de schéma de sortie, mais la description décrit précisément ce que renvoie l'outil : passage trouvé, numéro de page, lien vers le fac-similé. Elle couvre les cas d'usage, les langues, la lemmatisation, la traduction et les limites OCR ; un agent dispose de tout le contexte nécessaire pour décider et invoquer correctement l'outil.

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?

Le schéma couvre 100 % des paramètres, donc la baseline est 3. La description ajoute une vraie valeur sur q en expliquant le comportement par lemme et la traduction automatique, ce qui dépasse le simple libellé du schéma. Les paramètres livre, auteur et limit ne sont pas approfondis, mais le schéma les documente déjà correctement.

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?

La description utilise un verbe précis (« Recherche PLEIN TEXTE ») et identifie une ressource spécifique, le corpus océrisé de HebrewBooks.org. Elle distingue clairement la recherche dans le contenu des livres de la recherche par titres et précise ce que renvoie l'outil : passage, page et lien fac-similé. La différenciation avec Sefaria et sefaria_text est explicite.

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?

La description indique explicitement quand utiliser l'outil : ouvrages absents de Sefaria, minhagim locaux, responsa, ouvrages nord-africains et orientaux. Elle donne aussi une exclusion nette : pour un texte à citer, utiliser sefaria_text. Ce niveau de guidage est supérieur au minimum viable.

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