torah-mcp

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

Annotations already include readOnlyHint=true, and the description adds behavioral specifics beyond that: the interactive layout (Rachi and Tossafot dépliables), translation on click, and the default to the daf yomi of the day when no argument is provided. This gives the agent a good sense of the user-facing behavior without contradicting the read-only annotation.

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 well-structured: it leads with the core functionality, then the key interactive features, then the default behavior and usage guidance with examples. No redundant or filler content; every sentence contributes value.

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 single-parameter, read-only viewer with no output schema, the description is sufficiently complete. It covers what the tool does, the default behavior, and when to use it. The absence of return-value details is not a gap because this is an interactive viewer, not a data-returning API, and the readOnlyHint already signals safety.

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 coverage is 100% and the parameter description already includes the examples and default behavior ('Défaut : daf yomi du jour'). The tool description reiterates this default but adds no new semantic information about the 'ref' parameter beyond what the schema provides, so a baseline of 3 is appropriate.

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 a specific action: 'Affiche une page de Guemara en visualiseur interactif façon Vilna' (displays a Gemara page in an interactive Vilna-style viewer), with distinct features like Rashi/Tosafot and translation on click. It differentiates from siblings like sefaria_text or hebrewbooks_search by emphasizing the interactive viewer experience and the default daf yomi behavior.

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 provides explicit usage context: 'Utiliser dès que l'utilisateur veut VOIR ou étudier un daf' and gives concrete examples ('montre-moi le daf du jour', 'ouvre Berakhot 2a'). It does not mention when not to use the tool or explicitly name alternatives, but the guidance is clear enough for an agent to select it appropriately.

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

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

The description adds that output includes daily events ('événements du jour (Rosh Hodesh, fêtes, paracha)'), which is not in annotations. It doesn't discuss side effects, but readOnlyHint is true, so no write behavior is expected. It also doesn't contradict 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?

Two sentences, front-loaded with the primary function and followed by direction-specific instructions. No redundant content.

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 conversion tool with 100% schema coverage, the description covers both directions and output events. However, it lacks explanation of 'apres_coucher' and doesn't describe output format, though these are not critical for a basic conversion.

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 description defines which parameters are relevant for each conversion direction, supplementing the schema's individual descriptions. It clarifies that 'date' is for civil-to-Hebrew and the trio 'annee_h, mois_h, jour_h' for the reverse, but omits 'apres_coucher'.

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 defines the tool as converting civil dates to Hebrew dates and vice versa ('Convertit une date civile en date hébraïque (ou l'inverse)'), including daily events. The verb and resource are specific, but it doesn't explicitly differentiate from sibling calendar tools like sefaria_calendar or zmanim.

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?

It gives explicit instructions for both conversion directions: 'Sens civil→hébreu : passer date (YYYY-MM-DD)' and 'Sens hébreu→civil : passer annee_h, mois_h, jour_h'. This provides clear context on parameter selection, though it doesn't mention alternatives or exclusivity conditions.

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

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

The description adds a key behavioral trait: the text is actually read via Sefaria, never cited from memory, which is important for reliability and freshness. This goes beyond the readOnlyHint annotation (which only indicates safety) by disclosing the data source and accuracy guarantee. No contradiction.

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 two sentences, front-loaded with the main function and purpose. The second sentence adds valuable transparency about data sourcing without redundancy. Every word earns its place.

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?

With 2 params, full schema coverage, and a clear description, the tool is well-specified. The description also lists the output contents (text, translation, reference, links), which compensates for the lack of an output schema. A bit more detail on output format would be nice but is not essential.

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 covers 100% of the parameters, with 'ref' providing a Sefaria reference example and 'segments' explaining the maximum number of text segments. The description adds no extra parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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 composes a shareable source card ('fiche source') for a reference, including Hebrew text, translation, exact reference, and study links. The specific verb 'Compose' and the resource ('source card') make the purpose unambiguous. It is distinguished from sibling tools like sefaria_text by emphasizing the 'ready to share' formatting.

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 context: when the user needs a ready-to-share source card for WhatsApp/messaging, with translation and study links. It does not explicitly mention alternative tools or exclusions, but the context is clear. A slight gap remains in not naming when to prefer siblings like sefaria_text or sefaria_links.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral details beyond that: it is a local, exact calculation, and niqqud is ignored. This provides context about the tool's execution specifics and limitations.

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?

Two tightly packed sentences: the first states the core function and scope, the second adds method details and an important caveat. No wasted words, every sentence earns its place.

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?

The tool has one well-documented parameter and a read-only annotation. The description covers the purpose, methods, and a key behavioral caveat. While it does not describe the output format, the description is sufficient for a simple, well-scoped calculation tool.

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 already describes the single parameter 'texte' with 100% coverage. The description reinforces that niqqud is ignored, which slightly clarifies behavior but does not add new semantic meaning to the parameter itself. Baseline score is appropriate given high schema coverage.

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 calculates gematria for Hebrew text, word by word and total, listing specific methods. This verb+resource+scope structure distinguishes it from all sibling tools, none of which offer gematria calculations.

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 defines when to use the tool (for gematria calculations) and what it does, but does not explicitly mention alternatives or exclusions. Since no sibling tool overlaps with this functionality, the context is clear enough to guide an agent.

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

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

The annotations only provide readOnlyHint=true, indicating no data mutation. The description adds substantial behavioral context beyond that: it explains the mode changes Claude's interaction style (posing questions, defending positions, avoiding direct answers). It does not mention how the mode persists or how to exit it, but that is a minor gap for a behavioral mode toggle.

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 two sentences long, front-loaded with the primary action ('Charge le mode havrouta') and immediately explains the behavior and usage context. Every sentence earns its place with no redundancy or unnecessary detail.

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 low complexity (mode toggle, no parameters, no output schema) and the presence of readOnlyHint annotation, the description fully covers what an agent needs to know: the mode's purpose, the behavioral change, and when to invoke it. There are no missing critical details for correct invocation.

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 tool has zero parameters and the schema is empty, with schema description coverage at 100% trivially. No parameter documentation is needed, so the baseline score of 4 for zero-parameter tools applies. The description does not need to add 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?

The tool description clearly states its purpose: 'Charge le mode havrouta' with a specific verb and resource, and elaborates the behavior (Claude becomes an active study partner, asks questions, defends opposing positions, helps formulate kushiot). It distinguishes itself from sibling tools by being a mode rather than a content retrieval tool.

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 explicitly states when to use it: 'À charger quand l'utilisateur veut ÉTUDIER un texte, pas juste obtenir une réponse.' This provides a clear trigger context. It implies a 'when not' by contrasting 'not just get an answer', but does not explicitly name alternative tools or exclusion cases, though that is not critical for a mode switcher.

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

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

La description ajoute des détails utiles au-delà des annotations (readOnlyHint) : elle précise l'utilisation de l'API officielle et le retour de références vérifiées avec liens de lecture. Elle n'aborde pas les éventuelles limites de débit ou erreurs, mais le trait majeur (lecture seule) est couvert par les annotations. Donc bon niveau de transparence.

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 concise : deux phrases qui disent l'essentiel (action, ressource, API, résultat). Chaque élément apporte de l'information et il n'y a pas de répétition ni de verbiage inutile.

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?

Malgré l'absence de schéma de sortie, la description indique clairement ce que renvoie l'outil (références vérifiées avec lien de lecture) et son but. Pour un outil de recherche à trois paramètres optionnels, c'est suffisant pour que l'agent comprenne le contexte complet. Aucune information critique ne manque.

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 (limit, titre, auteur) avec des descriptions explicites. La description de l'outil ne fait que reformuler 'par titre et/ou auteur' sans ajouter de détail sur le format attendu des valeurs ou la combinaison des paramètres. La charge repose donc sur le schéma, ce qui correspond au niveau 3 de base.

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') et identifie clairement la ressource : le catalogue HebrewBooks.org, avec le type de contenu (seforim scannés) et la portée (~65 000). Elle mentionne aussi les critères de recherche (titre et/ou auteur) et le résultat (liens de lecture), ce qui la différencie nettement des outils frères comme sefaria_search.

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?

Le contexte d'utilisation est clair : dès la lecture, on comprend que l'outil sert à trouver des seforim dans le catalogue HebrewBooks. Cependant, la description ne mentionne pas explicitement quand privilégier cet outil par rapport à alternatives (ex. sefaria_search) ni les cas où il ne faut pas l'utiliser. Cela reste très compréhensible, donc 4 est approprié.

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

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

With readOnlyHint=true already provided, the description adds substantial behavioral context: it discloses that the skill uses verified primary texts via Sefaria, provides links to hebrewbooks.org for reading, and covers specific Jewish text domains. This goes beyond the annotation by explaining the tool's method and output behavior.

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 two sentences, with the first providing a dense but informative overview of the skill's purpose and the second a clear usage instruction. It is not overly verbose, though the enumeration of text genres makes the first sentence slightly long.

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 tool with no parameters, no output schema, and simple annotations, the description is complete: it explains what the skill does, when to use it, the topics covered, and the sources involved. The agent has enough information to know when to load this skill and what to expect.

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 tool has zero parameters and the schema reflects this, so there is no parameter information needed. The description does not need to explain parameters, and the baseline for zero parameters is 4.

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's purpose: 'Charge le skill d'étude des sources juives' (loads the Jewish sources study skill) and specifies the domain of religious questions (halakha, Talmud, Tanakh, responsa, hassidout, moussar). It distinguishes itself from sibling Sefaria tools by being a meta-skill loader, not a direct search or text retrieval tool.

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 explicitly says 'À charger AVANT de répondre à toute question religieuse' (to load before answering any religious question), providing a clear when-to-use trigger. However, it does not explicitly mention when-not-to-use or alternative tools, though it implies this skill should precede the use of Sefaria tools.

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

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

Annotations already declare readOnlyHint=true, matching the description's read-only nature. The description adds behavioral transparency by disclosing the return format: the best vocalization and variants for ambiguous words. This goes beyond annotations without contradicting them, though it does not cover error handling or rate 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 well-structured: the first sentence states the core function, and the second covers genres and return behavior. Every sentence adds value without redundancy or fluff.

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 low complexity (2 parameters, 1 enum), full schema coverage, and read-only annotation, the description covers all essential aspects: purpose, genre selection, and output. The return behavior is also mentioned, making the tool adequately understood without an output schema.

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 100%, so the baseline is 3. The description enhances parameter understanding by specifying that 'premodern' is the default and intended for rabbinic texts, while 'modern' and 'poetry' are other options. This adds practical guidance beyond the schema's enum descriptions.

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 a specific action: vocalizing unpointed Hebrew text via Dicta's nakdan. It identifies the resource ('texte hébreu non ponctué'), the method ('nakdan de Dicta'), and the genre options. This distinguishes it from all sibling tools, which are unrelated to vocalization.

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 when to use the tool (for vocalizing Hebrew text) and provides genre-specific guidance (premodern for rabbinic texts, modern, poetry). It lacks explicit exclusions or alternative tool references, but no sibling tool serves a comparable function, so the context is sufficient.

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

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

The readOnlyHint annotation already marks this as a safe read operation. The description adds value beyond that by enumerating the calendar types and specifying the default date behavior (today if no argument), which helps the agent understand the tool's scope without needing additional structured data.

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 a single, front-loaded sentence that efficiently lists calendar types and finishes with a concise default-date note. Every word serves a purpose, with no filler or redundant detail.

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 simple read-only tool with one optional parameter and no output schema, the description adequately sets expectations by listing the content types included in the calendars. It does not describe the return structure, but for this use case, the provided information is sufficient for an agent to understand what will happen.

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 fully describes the single optional 'date' parameter with its default value ('aujourd'hui'). The description merely restates this default in the 'sans argument' note, adding no additional semantics beyond what the schema already provides. With 100% schema description coverage, the bar is met, but no extra meaning is added.

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 that the tool provides daily study calendars (parasha, haftara, daf yomi, Rambam, halakha) with an optional date parameter. It identifies a specific resource and scope, though it does not explicitly compare against sibling tools like sefaria_search or sefaria_text, so it stops short of full differentiation.

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 gives a clear usage hint ('Sans argument : aujourd'hui') indicating the default behavior when no date is provided. It establishes a clear context for the tool's purpose, but it does not explicitly mention when to prefer this over alternatives or any exclusions.

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

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

The readOnlyHint annotation already signals a safe read operation, lowering the burden on the description. The description adds valuable behavioral context: it returns only linked references by category, not the full text, and directs the user to a subsequent sefaria_text call. This clarifies the tool's output scope beyond what annotations provide.

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 a single, front-loaded sentence that packs essential information: what the tool does, examples of content types, the output format, and the next-step tool. Every clause earns its place with no filler or redundant repetition of the schema.

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 low complexity, read-only annotation, and rich schema, the description is largely complete: it states the input (reference), optional filter (category), output (linked refs by category), and a follow-up action. It does not detail exact response structure, but for this simple lookup tool the guidance is sufficient.

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 coverage is 100%, so parameters are already documented. The description adds semantics by giving concrete examples of category values (Rachi, Tossafot, midrachim, halakha, responsa) and explaining that results are grouped by category. This enriches the meaning of the optional 'category' parameter and the output structure.

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 uses a specific verb ('Renvoie') and clearly identifies the resource: linked commentaries and texts for a Sefaria reference. It distinguishes itself from siblings like sefaria_text by stating it returns linked refs by category, not the text itself, and even points to sefaria_text for loading content.

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 when to use the tool: when you need commentaries or linked texts for a reference. It also gives workflow guidance by stating 'charger ensuite le texte voulu avec sefaria_text', indicating this tool is the first step before fetching full text. It does not explicitly mention exclusions or alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that search is full-text across the entire library in Hebrew or English, but doesn't disclose return format, pagination, or rate 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?

Two sentences, front-loaded with the action, no redundant wording.

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 simple search tool, the description covers purpose and usage well. The lack of an output schema means return format isn't defined, but the tool's nature makes it inferable; a brief mention of result type would make it fully complete.

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 coverage is 100%, with both query and size described. The description adds no additional parameter semantics beyond the schema.

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 uses a specific verb ('Recherche') and resource ('toute la bibliothèque Sefaria'), and explicitly states the use case (finding a source by words not reference), distinguishing it from siblings like sefaria_text or sefaria_calendar.

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 provides a clear use case ('retrouver une source dont on connaît les mots mais pas la référence'), but does not explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable context: it returns Hebrew with English translation if available, and includes a strong instruction to always cite from the text actually read, never from memory. This goes beyond the static annotation by guiding agent behavior and disclosing output content.

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 extremely concise: two sentences of substantive information. It front-loades the core purpose, provides examples, and ends with a critical usage rule. Every sentence adds value with no redundancy or filler, making it an exemplar of efficient writing.

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 simple tool with one parameter, no output schema, and read-only annotations, the description is complete. It states what is returned, gives reference format examples, and includes an important instruction about citing from the actual text. There is no missing information that would prevent an agent from using the tool 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?

Schema coverage is 100% with the 'ref' parameter described as a Sefaria-format reference in English. The description enhances this by listing concrete examples (e.g., 'Genesis 1:1', 'Berakhot 2a') that clarify acceptable formats and naming conventions. This adds meaning beyond the schema's generic description, lifting it above the baseline of 3.

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 retrieves the text of a Sefaria reference (Hebrew + English if available), which is a specific verb+resource. It implicitly distinguishes from sibling tools like 'sefaria_search' (searching) and 'sefaria_links' (related links) by focusing on the actual text content for a given reference.

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 provides clear context on what this tool is used for (getting text for a specific reference) and gives concrete examples of valid reference formats. It does not explicitly mention when not to use it or name alternative tools, but the examples and emphasis on citing from the actual text imply usage for known references. No exclusions are stated, fitting the 'clear context, no exclusions' level.

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

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

With readOnlyHint=true already indicating a safe read, the description adds meaningful behavior: the mode switch when chabbat=true (Shabbat schedule instead of daily zmanim) and the data source (Hebcal). It does not cover edge cases like parameter conflicts or error handling, but it adds value beyond the annotation without contradiction.

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 a single, front-loaded sentence with a parenthetical list of zmanim, followed by two short clarifying sentences. Every word contributes; there is no filler or repetition of schema details. Highly concise and well structured.

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?

Even without an output schema, the description lists the return categories (alot, netz, ..., chabbat times, paracha), explains location options, and names the data source. It does not cover response format or error conditions, but for this type of calendar tool the description is arguably complete enough for an agent to invoke 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?

The schema already documents most parameters, but the description adds semantic context by grouping 'Villes prédéfinies ou coordonnées libres', which clarifies how ville, geonameid, latitude/longitude/tzid relate. It also reinforces the chabbat boolean meaning. This compensates for the undocumented latitude/longitude fields, going beyond the schema's baseline.

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 identifies the resource (daily Jewish prayer times) and the specific verb/function ('Zmanim du jour', returns times like alot, netz, shkia, etc.). It also distinguishes the Shabbat mode via 'chabbat=true'. However, it does not explicitly contrast with sibling tools such as sefaria_calendar, so it stops short of full sibling differentiation.

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 provides clear usage context: daily zmanim by default, Shabbat entry/exit and paracha when chabbat=true, and input via predefined cities or free coordinates. It does not explicitly mention alternatives or when not to use this tool, but the guidance is sufficient for typical selection.

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