Torah Library

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral detail beyond those annotations: the no-path default behavior and the shape of the result ('description, subcategories and books'). The only omission is error behavior for invalid paths, which is minor for a read-only browse operation.

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 front-loaded, with two sentences that each carry distinct information. Listing the top-level categories and giving concrete path examples makes it immediately usable without unnecessary prose.

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 one-optional-parameter, read-only browse tool without an output schema, the description gives enough information: the default behavior, the path behavior, and the response content. No critical calling detail is missing.

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 category_path as a string with an example, and description coverage is 100%. The description adds meaningful semantic value by explaining that the parameter is optional and by illustrating deeper paths like 'Talmud/Bavli/Seder Moed' and 'Halakhah/Shulchan Arukh', which clarifies the hierarchy format.

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 action ('Browse the library's table of contents by category') and exactly what is returned for both no-path and path calls. It distinguishes browsing a hierarchical catalog from other library tools like search_library or get_book_info.

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 clear context for when to use the tool: 'With no path' returns top-level categories, and 'With a path like...' returns category details. It does not explicitly name alternatives or exclusions, but the branch-based usage is easy for an agent to act on.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the timestamp format (ISO date/time) but does not disclose return behavior or any edge cases, so it adds minimal context beyond 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?

The description is a single, front-loaded sentence with no wasted words. It directly states the purpose and the required timestamp format, making it concise and efficient.

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 lacks an output schema, and the description does not indicate what the tool returns (e.g., a boolean indicating modification status). There is also no usage guidance or caveats, leaving the agent uncertain about the tool's behavior and output.

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 only 50%: 'since' has a schema description, but 'id' does not. The description mentions 'source sheet' which loosely implies the id refers to a sheet, but it does not explicitly explain the id parameter or its type. It fails to compensate for the missing schema description.

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 verb 'check' and the resource 'source sheet' with a specific condition (modified since timestamp). It is precise and distinct from siblings like get_source_sheet or list_source_sheets, as it focuses on modification status.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It simply states what it does without context for selection.

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 mark the tool as read-only and idempotent, and the description adds valuable behavioral context beyond that: the ~180-day range limit, the fact that the Hebrew date advances after sunset, and the return contents (Hebrew date in English and Hebrew letters plus holidays/events). No contradiction with 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?

The description is compact and front-loaded with the core purpose, then uses clear arrow-style usage lines. Every sentence adds necessary operational detail without repetition 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?

Despite having no output schema and six optional parameters, the description covers both conversion directions, input formats, the range cap, the sunset edge case, and the return payload. An agent has enough information to invoke the tool correctly in either mode.

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 input schema already covers 100% of parameter documentation, so the baseline is 3. The description adds meaning by grouping parameters into conversion directions, explaining the end_date range behavior, and clarifying the after_sunset effect, which goes beyond the schema's individual 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?

Description states a specific verb and resource: 'Convert between Gregorian and Hebrew (Jewish) calendar dates.' It clearly distinguishes this tool from calendar-related siblings by emphasizing bidirectional date conversion rather than schedules, zmanim, or calendar listings.

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 explicit direction on when to use which parameters: 'Gregorian → Hebrew: pass gregorian_date' and 'Hebrew → Gregorian: pass hebrew_year, hebrew_month, hebrew_day.' It also explains when to set after_sunset. However, it does not explicitly name alternative sibling tools or state exclusions, so it stops short of full alternative routing.

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 cover readOnlyHint, idempotentHint, and destructiveHint, so the description is not obligated to repeat those. It adds the behavioral nuance that this works against multiple dictionaries and handles partial words, but it does not disclose what the response looks like (e.g., list of matches) or any quirks like language handling. With annotations covering the safety profile, this is a standard adequate score.

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, front-loaded sentence with no filler. It states the verb first and includes only essential information (the languages and dictionary names). 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?

For a three-parameter autocomplete tool with no output schema, the description is minimally sufficient but leaves some gaps. It explains the core input (prefix) and the dictionary options, but does not clarify what the return format is, how limit behaves, or edge cases. Given the simplicity of the tool and the presence of annotations, this is adequate but not comprehensive.

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 carry meaning for the parameters. It does explain that 'prefix' is a partial Hebrew/Aramaic word and lists the allowed dictionary values, which adds value beyond the raw schema. However, it neglects to explain 'limit' (e.g., max number of completions) and does not explicitly tie the quoted dictionary names to the 'dictionary' parameter, though it is implied.

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 with a specific verb ('Autocomplete') and resource ('partial Hebrew/Aramaic word') against a named set of dictionaries. It distinguishes itself from the sibling 'dictionary_lookup' by implying it handles partial words rather than full lookups, and it lists the specific dictionaries involved.

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 conveys a clear context: use this when you have a partial Hebrew/Aramaic word needing completions. However, it does not explicitly mention alternatives or when not to use it (e.g., when you already have a complete word, use dictionary_lookup). This is a clear context without exclusions, so it stops short of a 5.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable behavioral context beyond that: it handles prefixes/inflected forms and uses context_ref for disambiguation. This tells an agent how the tool behaves, not just what it is.

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 tight sentences, no filler. The primary action and scope are front-loaded, followed by useful behavioral and disambiguation guidance. 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?

For a read-only lookup tool with seven parameters, the description plus schema cover the essentials: required word, dictionary selection, context_ref usage, and split behavior. It lacks an explicit note about return shape, but there is no output schema and the read-only annotations reduce the need for safety caveats. A small gap remains in not pointing to dictionary_autocomplete when the user only wants suggestions.

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 71%, so the schema carries most parameter meaning. The description compensates for at least one gap: it explains context_ref as a disambiguation aid using the passage, and 'Handles prefixes/inflected forms' gives purpose to the splitting-related parameters. It does not cover always_split explicitly, but the description still adds real semantic value 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 opens with a specific verb and resource: 'Look up a Hebrew or Aramaic word in classic dictionaries (Jastrow, BDB, Klein, and others).' This clearly distinguishes the tool from browsing texts, calendar tools, or library search, and it names concrete dictionaries that make the scope unmistakable.

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 one actionable usage hint: 'Pass context_ref to disambiguate using the passage where the word appears.' It also implies use for inflected forms by saying 'Handles prefixes/inflected forms.' However, it never mentions when to prefer this over the sibling dictionary_autocomplete or get_term, so the tool-selection guidance is implicit rather than explicit.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds what the tool returns and how to use the result, but does not disclose behavior for ambiguous queries (e.g., whether multiple results are returned) or error handling.

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 concise sentences: the first front-loads the action and output, and the second adds a practical usage tip. Every sentence earns its place with no redundancy.

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 single-parameter tool with rich annotations, the description covers the essential return values and the practical downstream use. Missing an explicit statement about whether the tool returns one match or many, which 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?

The schema fully describes the only parameter (query) with examples and a minimum length, so the description adds no extra parameter-level meaning. Given 100% schema coverage, 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 verb 'Search' and the resource 'city/place by name', and specifies the returned data: place ids, country, and region. It is distinct enough from the sibling tools, though it does not explicitly name an alternative to differentiate against.

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 a clear when-to-use instruction: use the returned id as the 'location' argument when a city name is ambiguous. This is explicit about the intended use case, but it does not mention any alternative tools or exclusion scenarios.

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 the tool read-only and idempotent, so the description does not need to repeat safety behavior. It adds useful behavioral detail by promising to detect 'every' citation and by stating that it returns matched spans and canonical references, which is beyond what the annotations or schema reveal.

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, and every clause adds value: examples clarify scope and the last sentence states the return shape. There is no filler or repetition of schema/annotation 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?

With no output schema, the description appropriately discloses that the tool returns matched spans and canonical references. It could be more explicit about behavior when no references are found or about the exact form of spans, but given the read-only, idempotent annotations and clear input examples, the description is largely 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?

The text and title parameters already have schema descriptions, and language is an enum, so the schema carries most of the param-semantics burden. The description's examples clarify what kinds of citations the text parameter may contain, but it does not add guidance on the title or language 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 names a specific action ('Scan free text... detect every citation'), a specific resource ('Jewish source'), and gives concrete examples like 'Genesis 1:1' and 'Berakhot 2a'. This clearly distinguishes it from siblings such as parse_reference, which would handle a single reference rather than scanning for all citations.

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 provides clear context for when to use the tool: free-text documents such as a dvar Torah, article, or shiur notes. It does not explicitly name alternatives or say when not to use it, but the intended use case is evident and no exclusions are needed.

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 disclose the safety profile (read-only, idempotent, open-world, non-destructive), so the bar is lower. The description adds no additional behavioral details such as return shape, pagination, ordering, or empty-result behavior, but it does not contradict the 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 with no filler: the first states the core purpose, and the second delivers exactly the input guidance and examples an agent needs. It is front-loaded and 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?

For a one-parameter read-only tool with safety covered by annotations, the description is nearly complete: it defines the input, gives valid examples, explains how to resolve slugs, and implies the return value (a list of books). It does not describe the return fields, but the low complexity makes this a minor gap.

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 0%, yet the description fully compensates by naming the parameter, explaining what an author slug is, listing concrete examples, and telling the agent how to discover valid slugs via resolve_name. This is strong parameter-level guidance.

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 action and resource ('List the books written by an author'), and the title reinforces the scope. It does not explicitly differentiate from sibling tools like list_book_titles or get_book_info, though the focus on an author slug makes the distinction inferable.

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 concrete usage guidance: pass an author slug and provides example slugs plus a resolution path via resolve_name type AuthorTopic. It does not state exclusions or when to prefer an alternative, but the context is clear and actionable.

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, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context—it notes that availability counts are optional—but does not reveal any additional side effects, rate limits, or data-return nuances beyond what the annotations already convey.

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, dense sentence that front-loads the core purpose and then lists details. It is efficient and every clause contributes useful information, though the enumeration could be slightly more scannable with separators or short bullets. It avoids redundancy and stays focused.

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 no output schema, the description does a good job of indicating what the tool returns by enumerating the metadata categories and structure. It covers the main aspects an agent would need to decide whether to call it, though it does not mention error behavior or what happens for unknown titles. Given the simple parameter set and read-only nature, this 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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the meaning of include_structure with examples like Chapter/Verse and Daf/Line, and by tying include_availability to 'text availability counts.' It also enriches the notion of alternate structures with parshiyot for Torah books, which is not in 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 clearly states the tool returns metadata for a book and enumerates the specific fields: author(s), era, composition date and place, description, categories, alternative titles, section structure, chapter lengths, alternate structures, and optional availability counts. This distinguishes it from siblings like get_text (which returns content) or list_book_titles (which returns only titles).

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 no guidance on when to use this tool versus alternatives such as get_book_raw_index, get_text, or list_book_titles. It does not state exclusions, prerequisites, or a decision rule. The usage context is only implied by the tool's name and the metadata focus.

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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by promising an unabridged, complete schema tree and alternate structures, which implies a verbose raw response. It does not contradict the annotations, though it does not discuss size or pagination.

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 concise sentences: the first front-loads the core behavior and scope, the second routes to the appropriate sibling. No filler or redundancy.

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 one-parameter read-only tool with strong annotations and clear sibling routing, the description is largely sufficient. The main gap is the unhelpful parameter documentation, but the overall tool is simple enough that the description provides adequate context for 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?

Schema description coverage is 0%, and the description does not explain the 'title' parameter beyond the resource context. The property name is self-explanatory, but with no schema descriptions and no compensatory guidance about title format or exact-match requirements, the parameter semantics are under-specified.

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 states a specific verb and resource: a full, unabridged index record for a book, and names the included components (schema tree, match templates, alternate structures). It also distinguishes itself from get_book_info, which is described as the friendly summary alternative, so an agent can select the correct sibling.

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 'Use get_book_info for a friendly summary,' providing clear alternative guidance. It also implies the intended use case: call this when the raw, complete index record is needed rather than a summarized view.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful mode-specific behavior—'with its sheets' for slug and 'filterable by name' for public listings—but does not disclose pagination, sorting, or how limit applies.

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, well-structured sentence communicates the core purpose and all three usage modes without filler. The alternatives are separated by semicolons, making the branching logic easy to parse and front-loaded.

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 description is reasonably complete for a read-only browse tool, but it lacks key invocation details with no output schema and four undocumented parameters. It does not explain the precise semantics of contains, how limit interacts with collections vs sheets, or the response shape beyond a loose mention of sheets.

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 explains slug and user_id clearly, and hints at the contains parameter via 'filterable by name,' but it never names contains explicitly and says nothing about limit or its default/maximum behavior.

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 states a specific verb and resource: 'Browse collections of source sheets.' It also clarifies the three invocation modes—slug, user_id, or neither—making the tool's purpose immediately identifiable. This is specific enough to distinguish it from generic browsing or listing tools.

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 provides clear context for when to use each calling mode: pass slug for one collection, user_id for a user's collections, or neither for public collections. However, it does not explicitly compare against sibling tools like browse_library or list_source_sheets, nor state when not to use this tool.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these: with a commentator it returns full text, without it lists sources grouped by work, and the category default and optional text inclusion are explained. This gives the agent a clear picture of the tool's behavior without contradicting 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?

The description is well-structured with bullet points and front-loaded with the main purpose. It is somewhat long but every sentence adds value, explaining modes, categories, and supported works. It could be slightly trimmed, but the structure is clear and easy to scan.

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 complexity (7 parameters, no output schema), the description covers the key behaviors: the two modes, default category, text inclusion, and supported works. It does not describe return format or pagination, but with openWorldHint and idempotent annotations, this is acceptable. An agent has sufficient information to call 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 description coverage is 57%, with descriptions for ref, vowels, commentator, and include_text. The description adds meaning to the commentator parameter by explaining the conditional behavior (returns full text vs. lists sources), and clarifies the category parameter with its default and the enumerated list of categories. This partially compensates for the missing schema descriptions on limit and language, which are self-explanatory with defaults.

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 commentaries and connected sources for a passage, with a specific verb and resource. It distinguishes itself from sibling tools like get_text and get_passage_context by focusing on connected sources rather than the primary text or context. The two modes (with/without commentator) are explicitly described.

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 when to use the tool: when needing commentaries or connected sources for a passage. It explains the two modes and the scope of supported works (Tanakh, Talmud, etc.). However, it does not explicitly name alternative tools or state when not to use this tool, leaving some inference to the 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: it explains that candle-lighting, havdalah and fast times are only included when a location is provided, and it lists the default event categories. It does not describe the output structure, but no output schema exists and the coverage is adequate for a read-only tool.

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 core purpose, then a compact enumeration of event types. The usage instructions and defaults are packed into the second sentence 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?

For a tool with 27 parameters and no output schema, the description covers the essential decision points: how to specify the date range, the maximum span, the default event set, and the location-dependent behavior. It does not explain every parameter, but the schema handles those details. The description is sufficient for an agent to invoke the tool correctly in most cases.

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 78%, so most parameters already have descriptions. The description adds semantic value by clarifying the two usage modes (range vs year) and by summarizing which event categories are on by default (holidays, Rosh Chodesh, fasts, special Shabbatot, parsha). This goes beyond the schema, which lists each default individually.

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 opens with a clear verb and resource: 'List Jewish calendar events for a date range' and then enumerates the event types (holidays, Rosh Chodesh, fasts, etc.). It distinguishes itself from siblings like get_shabbat_times or get_parasha by covering the full calendar, not just one component. The scope is explicit.

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 instructions: pick start+end or year (+ optional month), max range ~1 year, and explains defaults. However, it does not explicitly name alternative tools for narrower queries (e.g., get_shabbat_times for only candle-lighting), so the when-not-to-use guidance is implied rather than stated.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by listing the specific study items included, but it does not disclose additional behavioral traits such as output format, pagination, or the effect of the 'israel' or 'timezone' parameters. It does not contradict the 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?

The description is a single, front-loaded sentence that immediately states the core function ('Today's study schedule items with exact references') before listing the included programs. While the list is lengthy, it is informative and every item contributes to the tool's scope. The structure is efficient and easy to parse.

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 schedule tool with no output schema, the description gives a good sense of the content returned but omits details about the return structure and how parameters like 'israel' or 'timezone' affect results. It also fails to clarify the distinction from the sibling 'todays_learning', leaving some context incomplete.

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 75% (date, custom, timezone have descriptions; israel does not). The description adds minimal parameter insight, only implying the date parameter with 'any date'. Since the schema already documents most parameters clearly, the description provides little extra meaning, aligning with 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 returns 'Today's (or any date's) study schedule items with exact references' and enumerates the specific study programs. It uses a specific verb ('get') and resource ('learning schedules'), making the purpose unambiguous. However, it does not differentiate itself from the sibling 'todays_learning' or other schedule-related tools, which slightly weakens clarity.

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 alternatives. The description provides no when-to-use or when-not-to-use conditions, and it does not mention any sibling tools or criteria for selection. Given the large sibling list including 'todays_learning', this is a significant gap.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by explaining what each kind returns and which parameters are required for word_count, going beyond the annotations without contradicting them.

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 scannable, with four short lines, clear mode names, and a helpful example. It contains no filler and front-loads the mode names, making it easy for an agent to quickly identify the relevant kind.

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 description gives enough detail for word_count but is incomplete for text_availability, where the book identifier is not specified, and it does not clarify the full parameter requirements for links_between_categories. Since there is no output schema, more explicit invocation details would be needed for full completeness.

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?

With 0% schema description coverage, the description must carry the parameter documentation burden. It explains the kind enum and maps word_count to title, version_title, and language, but it leaves links_between_categories implicit regarding category_a/category_b and does not specify which parameters text_availability needs.

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 three distinct statistic kinds with concrete meanings and an example, so an agent can understand what the tool computes. It does not explicitly distinguish this tool from sibling getters like get_book_info or get_text_versions, but the 'statistics' scope and bulleted kinds make the purpose reasonably clear.

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 per-kind guidance, such as 'needs title, version_title, language he/en' for word_count, and an example for links_between_categories. However, it does not explicitly say when to prefer this tool over sibling tools or state any excluded use cases, leaving most selection logic to inference.

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 establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context that the result includes image and thumbnail URLs specific to manuscript/early-print sources, but it does not describe edge cases like missing images or how the passage reference resolves.

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 focused sentence with concrete examples (Vilna Shas, Venice 1523, Munich manuscript) and no redundant wording. Every part contributes to understanding the tool's output and scope.

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 parameter and no output schema, the description is mostly adequate, but it omits the reference format and any direction about when this tool is appropriate versus other image or text tools. The annotations cover safety, so the main gap is usage and ref semantics.

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 0%, so the description bears the burden of explaining the 'ref' parameter. It only says 'for a passage,' which gives a rough semantic hint but does not specify the expected reference format, syntax, or supported passage types.

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 conveys a specific resource—images of manuscripts and early printed editions—for a given passage, including image and thumbnail URLs. It does not explicitly differentiate from the sibling get_text_image, but the examples and scope make the tool's purpose easy to identify.

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 no guidance about when to choose this tool over alternatives such as get_text_image or get_book_info. It only says 'for a passage,' leaving the usage context implicit rather than explicit.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the content of the response (full reference, aliyot, haftarah, next date) but does not disclose additional behavioral traits such as auth requirements or error behavior, which are not relevant here. It is consistent with annotations and adds some value.

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 sentence that front-loads the purpose ('Details for a weekly Torah portion by name') and then lists the return fields. There is no filler or 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?

For a single-parameter read-only lookup with no output schema, the description covers the purpose, input format, and return fields. It does not discuss edge cases or error handling, but given the tool's simplicity and the annotations covering safety, it is sufficiently complete for an agent 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?

Schema description coverage is 100% (parasha name in English transliteration). The description adds concrete examples (Noach, Lech Lecha, Ki Tisa) that clarify the expected input format, providing practical value beyond the schema's minimal definition.

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 states the resource (weekly Torah portion) and specifies the exact details returned: full reference, aliyot, haftarah, and next reading date. It is clear and specific, though it does not explicitly distinguish from sibling tools like get_torah_reading or parsha_study_pack; the examples and scope make the purpose unambiguous.

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 when details about a specific parasha are needed, but it provides no explicit guidance on when to use this tool versus alternatives like get_torah_reading or parsha_study_pack. There is no mention of exclusions or conditions, so the usage context is implied rather than stated.

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 convey read-only, idempotent, non-destructive behavior. The description adds that multiple refs are resolved to their logical passages, which is useful, but it does not disclose output structure or how malformed references are handled. No contradiction with 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?

The description is a single efficient sentence with no filler. It front-loads the input condition and immediately states the output promise.

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 one-parameter, read-only tool, the description plus annotations are almost sufficient to invoke it correctly. Since there is no output schema, a bit more detail about the returned passage structure would complete the picture, keeping this just below perfect.

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%, but the description compensates by labeling 'refs' as segment references and giving a concrete example ('Berakhot 2a:1'). This adds real meaning beyond the raw string-array schema, though it does not enumerate all accepted reference formats.

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 states a specific verb ('return') and resource ('full logical passage/sugya') and anchors it with a concrete input example ('Berakhot 2a:1'). This clearly distinguishes the tool from generic text-retrieval or parsing siblings.

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 condition for use is implied: when you have segment references and want the containing passage. However, the description does not explicitly contrast alternatives like get_text or parse_reference, nor does it say when not to use this tool, so guidance remains implicit.

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 establish read-only, non-destructive, idempotent, and open-world behavior. The description adds the key behavioral detail that the output pairs a random source with its topic, and 'random' signals nondeterministic selection. No contradiction with 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?

One concise sentence front-loads the core action and result, then adds a single relevant use case. No filler or repeated schema information.

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 zero-parameter read-only tool, the description covers the output composition and a typical use case. It does not specify the exact return shape, but in the absence of an output schema the brief statement is sufficient for an agent to decide to call it.

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, so the baseline is 4; there is nothing for the description to clarify about inputs. The schema coverage is effectively 100% and the description correctly omits param details.

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 opens with a specific verb ('Get') and a clear deliverable: a random source paired with the topic it illustrates. This distinguishes it from siblings like get_random_text, though it does not explicitly name the alternative or state the exclusion.

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 suggests a context ('handy for a daily inspiration or quiz') but gives no guidance on when not to use it or which sibling to choose instead. Given the ambiguity with get_random_text, the usage guidance is implied rather than explicit.

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, idempotentHint, and destructiveHint, covering safety and non-mutation traits. The description adds the 'random' nature and optional filters, which is useful. However, it does not disclose the return format, pagination, or potential limitations (e.g., if filters are invalid). Given the annotations carry the safety burden, this is a moderate contribution.

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 states the primary action first, then adds the optional filters. It is efficient with no redundant wording, making it easy to parse quickly.

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 random-text tool with no output schema, the description covers the essential function and parameter usage. However, it does not address how to differentiate this from related tools like get_random_source_by_topic, nor does it describe the expected output structure (e.g., passage text with reference). The presence of many siblings increases the need for clearer differentiation.

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 only 33% (vowels is described). The description compensates for titles and categories by explaining their meaning with concrete examples (e.g., categories ['Tanakh'], titles ['Psalms', 'Proverbs']). It does not fully specify valid values or interaction rules between parameters, but it does add meaningful context beyond the bare 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 clearly states the tool's function: 'Get a random passage' with optional filtering by books or categories. It uses a specific verb and resource, and provides examples of valid filter values. While it doesn't explicitly differentiate from sibling tools like get_random_source_by_topic, the core purpose is unambiguous.

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 offers no guidance on when to use this tool versus alternatives, nor does it specify any conditions or exclusions. The example of categories and titles is more about parameter format than usage context. An agent has to infer when this tool is appropriate rather than being told.

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 the tool read-only, idempotent, open-world, and non-destructive. The description adds that results are an overview with grouped counts and related items, but it does not disclose output structure, pagination, or how the included categories are actually returned.

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 focused sentences with no filler. The first states the tool's scope with an itemized list; the second provides a usage directive. Everything included 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?

There is no output schema, so the description must convey what the tool returns; it does list content categories, but not the shape of the response or the behavior of the include parameter. The core use case is clear, but parameter and result details remain under-specified.

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%, and the description never explicitly explains ref or include. The term 'passage' maps to ref and the output categories echo the include enums, but an agent must infer the reference format and how include affects the response.

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 names the operation (overview of everything connected to a passage) and enumerates concrete content categories: counts by category/book, related topics, source sheets, manuscript images, and web articles. It also distinguishes itself from the sibling tool get_commentaries, making selection straightforward.

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 explicitly recommends using this tool for exploration before drilling in with get_commentaries, giving clear context. It does not mention other alternatives or exclusions, but the stated use case is enough to guide basic selection.

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 cover safety (read-only, idempotent, non-destructive), and the description adds a small amount of behavioral context by saying the result includes a description and key sources. It does not disclose how the 'current' date is determined or how the israel flag affects results, so transparency is only partial.

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 compact sentence delivers the essential purpose, the two kind values, and the output contents with no filler. The key decision information is front-loaded.

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 lookup with only one required parameter, the description covers what the tool returns and when to use it. The main gap is the unexplained israel flag and the exact behavior with a custom date, but given the low complexity and rich annotations, the missing context is minor.

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 only 33%; the description helps by mapping the kind enum to 'parasha' and 'holiday' and adding the 'curated topic' meaning. However, it adds nothing about the israel parameter and only restates the date behavior that the schema already provides, leaving a real semantic gap.

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 states a clear verb ('Get'), a specific resource ('curated topic for the current parsha ... or the current/upcoming holiday'), and the expected contents (description and key sources). It does not explicitly distinguish itself from sibling tools like get_parasha or holiday_sources, so it falls short of a 5.

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 concrete temporal triggers: use for the current parsha or the current/upcoming holiday. It does not name alternative tools or explain when not to use it, but the context is clear enough for a read-only lookup.

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 the tool read-only, idempotent, and non-destructive, so the safety burden is covered. The description adds useful behavioral scope: it covers a specified week, includes Yom Tov, and returns parsha/holiday readings. It does not contradict annotations and gives a solid picture of result contents.

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 dense sentence with no filler. It front-loads the two main output types and then adds the important boundaries: coming or specified, Yom Tov, readings, and location.

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 100%-covered schema, the read-only annotations, and the description's clear output summary, an agent can correctly select and invoke this tool. The main gap is the lack of any pointer to related tools for other calendar or reading needs, but the description is otherwise 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 description coverage is 100%, so the baseline is 3. The description does not add much parameter-level meaning beyond what the schema already provides, such as the date default, location alternatives, and candle/havdalah minute adjustments.

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 states exactly what the tool returns: candle-lighting and havdalah times for Shabbat and Yom Tov, plus parsha and holiday Torah readings, for a location. It is specific enough to distinguish this from siblings like get_zmanim or get_torah_reading, which cover only part of this scope.

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 Shabbat/Yom Tov times and Torah readings are needed together—but gives no explicit guidance about alternatives or exclusions. It does not name siblings such as get_zmanim or get_parasha, leaving the agent to infer the boundary.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral nuance about the three kinds of tags (trending, all, user) and sorting options, which is useful. However, it does not disclose potential defaults, pagination, or that user_id is required when kind=user. With annotations covering the main safety traits, the additional value is moderate.

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, efficient sentence that front-loads the core resource and enumerates the three modes in a compact list. Every phrase adds value, with no filler or redundancy. The structure is easy to parse at a glance.

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 is simple with no output schema, but the description leaves gaps: it does not explain the relationship between kind and user_id (e.g., user_id required when kind=user), the meaning of limit, or default behavior. While annotations cover safety, an agent might mis-call it without knowing these dependencies. For a 4-parameter tool, more explicit guidance is needed.

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 0%, so the description must compensate. It explains the 'kind' parameter (trending, all, user) and indirectly the 'sort_by' option ('sorted by count or alphabetically'). However, it omits 'limit' and 'user_id' semantics, including that user_id is only relevant for kind=user and may be required. This is a partial compensation, leaving two of four parameters undocumented in the description.

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 resource ('source-sheet tags') and the action ('get') with three distinct modes (trending, all, user). It is specific and distinguishes this tool from siblings like get_source_sheet or list_source_sheets by focusing solely on tags. No ambiguity remains about what it returns.

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 it (when you need tags), but it does not explicitly mention alternatives or conditions like 'use this for tags, not for sheets'. There is no exclusion or contrast with other tools. The context is clear but not directive.

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 contradicts the openWorldHint annotation by claiming 'each source ... in order,' implying a complete result set, while the annotation signals non-exhaustive results. It also fails to mention that max_sources may cap returned sources, leaving a significant truncation behavior undisclosed.

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 concise, front-loaded sentences with no filler. It leads with the resource and return contents, then gives the batching constraint. 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?

There is no output schema, so the description must carry the return-value burden; it names the fields but overclaims completeness. It also omits max_sources behavior and any error/missing-sheet behavior, leaving a needed gap for reliable 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?

Schema description coverage is 0%, so the description must compensate for both parameters. It explains that ids can be multiple and up to 10 sheets can be fetched, but it never explains max_sources or its effect on the returned source list, so an agent cannot infer the truncation behavior.

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 and resource: getting a user-made source sheet by id. It also lists what is returned—title, author, tags, sources, and commentary blocks—which clearly distinguishes it from browse_library, list_source_sheets, and get_sheet_tags.

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 makes the use case clear: fetch specific sheets when you already have their ids, with batching up to 10. It does not explicitly name alternative tools or exclusion conditions, but the 'by id' framing is strong enough context.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds only that the tool returns 'status/result', which is a minimal behavioral disclosure. It does not say what happens for a missing task, a still-running task, or a failed task, but with the annotations carrying the main burden, this is a passable but not rich behavioral description.

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 sentence with no filler; the action, resource, and parameter are all present and front-loaded.

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 no output schema, the description is the only source of what the response contains. 'Status/result' is vague–it does not enumerate possible statuses (pending, running, completed, failed), define 'result', or indicate whether a completed result is embedded or referenced. An agent polling this tool would not know what to expect in the response body or how to detect success.

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 for the bare 'task_id' string parameter. It merely says 'by task_id', which restates the parameter's role without explaining where the ID comes from, its format, or any relationship to a previously submitted background job. This is a clear gap for a tool whose only input is an opaque identifier.

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 and resource: 'Check the status/result of a background task' and names the identifier 'task_id'. The example 'long reference-detection job' clarifies the intended use case, and it is clearly distinct from the sibling tools, which are all library/resource queries rather than async task management.

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 clearly implies when to use: when an agent has a task_id from a background job and needs its status/result. It provides the example of a long reference-detection job as context, but it does not explicitly mention when not to use the tool or name alternatives. Given the absence of any sibling tool that handles background tasks, this is reasonably complete context.

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 establish readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral promise about what the response contains: Hebrew/English titles and alternate spellings. It does not mention unknown-term behavior, but the annotation coverage lowers the burden.

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 communicates the action, resource scope, output contents, and examples with no filler or redundancy. Every clause 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?

For a one-parameter, read-only lookup with no output schema, the description supplies the essential elements: what to pass, what kind of terms are accepted, and what will be returned. The main gaps are exact result structure and not-found handling, but the low complexity and strong annotations keep this from being incomplete.

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 input schema provides zero description coverage for the 'name' parameter, so the description must compensate. It does clarify that the parameter is a named term and offers examples ('Noach', 'Bereshit', 'Perek'), but it leaves language, case sensitivity, and partial-name behavior unspecified.

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 ('Look up') and identifies a resource ('a named term') with concrete examples and output fields (Hebrew/English titles, alternate spellings). It is clear, though it does not explicitly differentiate itself from near-neighbor siblings like get_parasha or dictionary_lookup.

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 by scoping it to named terms and giving examples, but it provides no explicit when-not-to-use guidance or alternative routing. With many siblings such as get_parasha, resolve_name, and dictionary_lookup, this leaves some ambiguity.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuine value beyond that: segment-by-segment alignment, the return shape {n, he, en}, and next/previous section refs for paging. These behavioral details are not available from the annotations or input schema, with no contradictions.

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 core purpose is front-loaded in the first sentence, and every following sentence earns its place: scope, reference examples, return structure, paging, and failure fallback. It is a bit dense, but given the heterogeneous reference syntax it must convey, the length is justified with no filler.

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 complex 7-parameter tool with no output schema, the description compensates well by specifying the return segments shape and paging mechanism. The remaining gaps are minor: no guidance on when to prefer get_texts_bulk, and no explanation of how version_title or translation_language interact with the language parameter — but these are partially covered by the 100% schema descriptions.

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 the baseline is 3. The description earns a 4 by substantially enriching the most critical parameter (ref) with nine concrete reference examples covering books, verses, Talmudic folios with segment ranges, and commentaries — far more than the schema's single example provides.

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?

"Fetch any text from the Jewish library by reference" states a specific verb, resource, and retrieval mechanism, and the coverage list (Tanakh, Talmud, Midrash, etc.) and reference examples clearly distinguish it from siblings like browse_library, get_random_text, get_torah_reading, and search_library. An agent can immediately tell this is the by-reference text fetcher, not a browsing or topic-based 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 makes the usage context clear (fetch by structured reference, with nine example formats) and gives an explicit fallback: "If a reference fails, try resolve_name." However, it never states when NOT to use this tool versus close siblings such as get_texts_bulk (bulk fetching) or get_torah_reading (specific structured readings), so exclusions are incomplete.

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 cover safety traits (readOnlyHint, idempotentHint, destructiveHint), so the description's burden is lower. It adds useful output context (PNG format, social sizing) but does not disclose mechanical behaviors like how the image is returned (e.g., URL vs. binary) or any limitations. It does not contradict the 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?

The description is a single, well-structured sentence that front-loads the verb and resource. Every clause adds value (PNG format, social platform), with no redundant or filler 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?

The tool is relatively simple, but the description does not clarify how the generated image is delivered to the caller (e.g., URL, base64, file). It also does not explain the 'language' parameter's role, though the enum values are self-explanatory. Given the absence of an output schema, a bit more detail on return format would improve completeness.

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 only 33%; only 'ref' has a description. The tool description does not elaborate on 'language' or 'platform' parameters beyond the enums, and the phrase 'sized for a social platform' only hints at the platform parameter without explaining the options. This fails to compensate for the low 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 states a specific action ('Generate'), a specific resource ('a shareable image (PNG) of a short passage'), and a clear use context ('sized for a social platform'). This clearly distinguishes it from sibling tools that fetch text or metadata, and the title reinforces the purpose without being a tautology.

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 does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusion conditions. However, its purpose is obvious (image generation), and it is distinct from the many text-retrieval siblings, so usage is implicitly clear but not explicitly guided.

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, destructiveHint=false, and idempotentHint=true, so the agent knows it's a safe, non-destructive, idempotent read. The description adds the up-to-30 limit and the fact that it returns both Hebrew and English, which is useful. However, it does not disclose behavior on invalid references, response format, or edge cases, leaving some gaps 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?

Two concise sentences that front-load the core purpose and then add key constraints (Hebrew and English, up to 30). Every word earns its place; there is no redundancy or vagueness. The structure is ideal for quick agent parsing.

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 bulk read tool with well-documented schema and safety annotations, the description covers the essential usage: purpose, return content, and limit. It does not detail error handling or response structure, but that is acceptable given the tool's simplicity and the presence of an output schema (which is absent here). The description is adequate for an agent 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?

Schema description coverage is 100%, with detailed descriptions for refs (including examples) and vowels (explaining 'full' vs 'none'). The description adds no additional parameter semantics because the schema already handles it. Baseline 3 is appropriate since the schema fully documents the 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?

Clearly states the verb 'fetch' and the resource 'many short references', with examples of what that means ('verses or commentary lines'). It adds the constraint of up to 30 references and that both Hebrew and English are returned, making the purpose specific. However, it does not explicitly differentiate from sibling tools like get_text, so it misses the opportunity to distinguish itself by name.

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 when you need multiple short texts in one call, but it does not explicitly state when NOT to use it or mention alternatives. For instance, it doesn't say 'for a single text use get_text'. The bulk nature is clear, but the guidance is implicit rather than explicit.

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 readOnly, openWorld, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds useful response-field context (language, version title, license, source) but no further behavioral caveats like pagination or completeness guarantees.

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 compact sentences, front-loaded with purpose and followed by the essential usage pointer. No filler or redundant restatement 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?

For a simple read-only listing tool, the description gives the scope, return fields, and the next step. It is nearly complete, though it could strengthen the sibling distinction and clarify the effect of omitting the optional language filter.

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 parameters 'book' and 'language' are already documented. The description adds only an indirect semantic note about version_title being consumed by get_text, which is helpful but not necessary for understanding either parameter.

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 opens with a specific verb and resource: 'List every available edition and translation of a book', and names the returned fields. It is clear, but it does not explicitly distinguish itself from the similar sibling 'list_translations'.

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 clearly points to the follow-up tool: 'Use a version_title with get_text to read a specific translation', which implies the main use case. However, it does not state when not to use this tool or how it compares with sibling 'list_translations'.

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 read-only, idempotent, and non-destructive behavior is already covered by annotations, so the description's job is lighter. It adds valuable non-obvious behavioral context, namely that results are curated and ranked ('ordered by importance') and that the response includes both a description and top sources, which goes beyond what the annotations alone convey.

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 core behavior is front-loaded in the first sentence, with no wasted words, and the second sentence adds a practical routing hint. The parenthetical examples are somewhat dense but directly serve the agent's need to construct a valid slug.

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 that there is no output schema and only one required parameter, the description adequately communicates the returned content and ordering for a default call. It does not describe the response shape or the effect of include_related_topics, but the strong annotations and simple parameter defaults reduce the risk of misusing the 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?

Schema description coverage is 50%, so the description must help compensate for undocumented parameters. It does help with the slug parameter by giving valid examples and pointing to slug-resolution tools, and 'top sources' loosely relates to max_sources, but it never explains what max_sources controls or what include_related_topics returns, so compensation is only partial.

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 opens with a specific verb and resource ('Get a curated topic') and defines the scope by enumerating valid categories such as person, concept, holiday, mitzvah, or object. It also states what is returned — a description and top sources ordered by importance — which differentiates it from sibling tools like get_topic_graph or get_term.

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 for when to use the tool: when a curated topic page with description and top sources is needed. It also gives explicit routing guidance for the main prerequisite, slug discovery, by directing the agent to resolve_name or search_topics, but it does not spell out when-not-to-use alternatives like get_topic_graph or get_term.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the concept of a graph/network and enumerates link types, which is useful behavioral context beyond the annotations. However, it does not disclose potential limitations (e.g., whether the graph includes the source topic, depth, or pagination). Given the annotation coverage, a 3 is appropriate.

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 no filler. The primary purpose is front-loaded, and the optional filter is presented second. Every word earns its place; it is 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?

With no output schema, the description should clarify what the response looks like. It states the tool returns a 'network of topics connected to a topic,' which implies a graph structure, but does not describe the format (e.g., nodes and edges), whether the source topic is included, or any pagination or depth limits. Given the complexity of a graph tool, this is a notable gap, but the description is still adequate for basic usage, hence a 3.

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 implicitly explains 'slug' as the topic to which connections are sought, and explicitly describes 'link_type' as an optional filter with examples. This adds meaningful meaning beyond the bare schema property names. However, it does not specify the exact format or allowed values for link_type beyond examples, so a 4 rather than 5.

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 states a specific verb ('Get') and a specific resource ('the network of topics connected to a topic'), with clarifying examples ('students/teachers of a sage, parts of a concept'). It clearly distinguishes this from sibling tools like get_topic, which would retrieve a single topic, and get_related_content, which likely returns related items. The optional link_type filter further refines the purpose.

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 explains the optional link_type parameter and gives examples of allowed values, but it does not provide explicit guidance on when to use this tool versus alternatives like get_topic, get_related_content, or recommend_topics. The usage context is implied by the purpose but not stated as exclusions or 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 annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds no further behavioral details beyond the content of the returned reading schedule, which is useful but not additional transparency about side effects or constraints.

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, well-structured sentence that leads with the core purpose, then packs in the key output elements and the two main option axes without any filler or repetition.

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 absence of an output schema, the description does well to enumerate the returned data: parsha/holiday name, aliyot with verse ranges/counts, maftir, haftarah, and special readings. Remaining details like defaults and date-range limits are already present in the input schema, so the combination is sufficiently complete for an agent to call 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 80%, but the description adds meaning beyond the schema by explaining 'Israel vs Diaspora' (clarifying the otherwise undocumented israel parameter) and 'triennial cycle' (reinforcing the triennial flag). It also relates date/end_date to the 'date or date range' concept, giving useful semantic context.

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 ('Torah and Haftarah readings') and the specific output components (aliyah verse ranges, maftir, haftarah, special readings). It is more specific than merely restating the name, though it does not explicitly contrast itself with sibling tools like get_parasha or get_learning_schedules.

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 phrase 'for a date or date range' gives a clear context for when the tool should be used, and the mention of Israel vs Diaspora and triennial cycle signals relevant use-case variations. It does not name alternative tools or provide exclusions, but the usage context is explicit enough for an agent to infer the right scenario.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds the slug format example, but no further behavioral traits such as auth requirements, rate limits, or response size are disclosed. This is acceptable given annotation coverage.

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, front-loaded sentence that states the purpose and gives an example. Every word earns its place; no filler or redundant phrasing.

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 no output schema, the description should indicate what the returned profile contains (e.g., name, bio, contact info). It only says 'public profile', which is vague. While the tool is simple, an agent might need to know whether to expect a specific structure. The scope (library user/author) is clarified, but return details are missing.

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 input schema has zero description coverage for the slug parameter, so the description must compensate. It provides an example ("dovid-birk") which clarifies the format, but it does not explain how to obtain a slug, what constraints exist, or what the profile contains. The compensation is minimal but helpful.

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 a public profile of a library user/author by slug, with a concrete example. It distinguishes itself from siblings like get_author_works (which fetches works) and get_source_sheet (which fetches a sheet) by explicitly scoping to profile data.

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?

No guidance is given on when to use this tool versus alternatives. While the slug example hints at usage, there is no mention of when to prefer this over get_author_works or other user-related tools, nor any exclusions or prerequisites.

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 cover readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to restate safety. It adds valuable behavioral details: handling after-sunset events, Adar in leap years, and Cheshvan/Kislev edge cases, which are critical for correct Hebrew calendar computation. It also states the batch limit (up to 10 entries), which influences how an agent should structure calls. No contradiction with annotations is present.

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 succinct, with the core purpose in the first sentence and supplementary details in the second. It avoids redundancy and front-loads the most important information, making it easy for an agent to parse quickly. Every sentence contributes meaningful detail without unnecessary elaboration.

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 computation tool, the description covers the main inputs and edge cases that are essential for correct usage. It does not explicitly state the return format, but since the purpose is to compute dates, the output (list of Gregorian dates) is inferred. The batch limit and edge-case handling are included, which are critical nuances. Missing are details about error handling or behavior when no dates are found, but these are minor given the scope. Overall, it is fairly complete 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 describes each parameter, but coverage is only 50% (the 'entries' property lacks a description). The description clarifies that 'date' is the original Gregorian date and specifies the batch limit (up to 10 entries), which aligns with maxItems. However, it does not explain the 'years' parameter or the meaning of 'type' beyond the enum values, leaving the agent to rely on the schema. The added context is helpful but not enough to fully compensate for the missing description of 'entries'.

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 verb ('Compute') and resource ('upcoming Gregorian dates for yahrzeits, Hebrew birthdays or Hebrew anniversaries') derived from an original Gregorian date. It distinguishes the tool's function from broad calendar tools like get_jewish_calendar, though it does not explicitly name an alternative sibling. The purpose is unambiguous and informative.

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 no guidance on when to use this tool versus alternatives such as convert_date or get_shabbat_times. It does not mention any exclusions or edge scenarios that would route the agent to another tool. The intended use cases are implied by the description (yahrzeits, birthdays, anniversaries) but no explicit direction is given.

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 establish that this is read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond annotations by recommending a max range of ~7 days and listing the exact set of returned time categories, including variant opinions.

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 one compact, front-loaded sentence with no filler. The long list of zmanim is necessary to convey the tool's output richness, and the parenthetical range recommendation is tucked in without disrupting the main clause.

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 no output schema present, the description does well to enumerate the specific return values. Combined with fully documented parameters, an agent can reasonably understand what the tool returns and how to invoke it. It stops short of fully complete only because it lacks explicit routing guidance against sibling time-related tools.

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 all parameters are already documented in the schema. The description reinforces the relationship between the primary parameters (location, date, date range) but adds little semantic value beyond what the schema provides.

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 returns halachic times of day for a location and date/date range, and it enumerates the specific zmanim included. This makes the primary resource and scope unmistakable. However, it does not explicitly differentiate itself from sibling tools like get_shabbat_times or get_jewish_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 conveys the core usage context: a location and date, with an optional date range and a recommended maximum of ~7 days. It does not mention when to prefer this tool over related tools such as get_shabbat_times, nor does it provide exclusions or alternatives.

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 cover readOnly, idempotent, openWorld, and non-destructive traitsabb. The description adds useful behavioral context by naming the return categories, including that sources come 'with text', and does not contradict any 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 one clear, front-loaded sentence followed by useful examples. The example list is somewhat long, but every part of the main 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 description is adequate for the core holiday-sources use case.output, but it leaves the likely date-related semantics of israel and the meaning of max_sources unexplained. With no output schema and two unexplained parameters, more detail is needed for full completeness.

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 only 33%, yet the description only glosses the 'holiday' parameter through context and examples. The israel and max_sources parameters are undocumented in both the schema and the description, leaving their effect on the return value opaque.

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 states the tool returns holiday-specific data—dates, description, Torah/Haftarah readings, and classical sources—for the next or named Jewish holiday. It is clear about scope and content, and examples reinforce valid inputs大方, but it lacks an explicit verb and does not distinguish itself from siblings by name.

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 use case: Jewish holidays, either the next one or a named one. It does not, however, explain when to choose this over related tools like get_torah_reading or get_jewish_calendar, so it misses the explicit exclusions needed for a 5.

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 cover read-only, idempotent, and non-destructive behavior. The description adds value by specifying the output format ('canonical titles with their category') and the search scope (all books in the library, by title substring). It does not contradict annotations and provides context beyond the structured metadata.

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, focused sentence that front-loads the action and key criteria. Every clause adds information, with no redundancy or filler.

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 with three optional parameters and no output schema, the description covers the core behavior, search criteria, and return format. It omits minor details like result ordering or limit behavior, but these are either in the schema or not critical for a basic search operation.

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 'contains' and 'category_path' with examples. The description reinforces that the search is on titles, but does not add meaningful detail about the 'limit' parameter, which is undocumented in the schema. With 67% schema coverage, the description only marginally compensates for the gap, so it is adequate but not exceptional.

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 verb 'search', the resource 'list of all books in the library', and the specific criteria (English or Hebrew title, optional category path). It distinguishes itself from siblings like search_library, which likely searches full text, by focusing on titles. This is specific and unambiguous.

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 for finding books by title, but does not explicitly state when to prefer this tool over alternatives like search_library or get_book_info. There is no mention of exclusions or specific conditions that would trigger use of this tool, leaving some inference to the 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds behavioral context not in annotations: the public-only scope, paging, sortable by 'views' or 'date', and the default 'latest' behavior when no ref/user_id is provided. This is useful and consistent with the 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?

The description is a compact bulleted list with the main verb and resource front-loaded. Each bullet adds a distinct mode without unnecessary prose, making it easy to scan and parse.

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 five optional parameters and no output schema, this is workable but incomplete. The main modes are covered, but the description leaves interaction rules unspecified (e.g., whether ref and user_id can be combined, and whether paging/sort applies to all modes or only the user mode). An agent may need to make assumptions for edge combinations.

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?

With 0% schema description coverage, the description carries the burden for all five parameters. It gives real meaning for ref, user_id, and sort_by, and mentions 'with paging' for limit/offset, but it does not explicitly define how limit and offset behave across modes or clarify whether ref and user_id can be combined. This is partial compensation, not full.

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 uses the verb 'List' with the resource 'public source sheets' and enumerates three lookup modes (by passage, by user, latest), which is specific enough for an agent. It does not explicitly name or contrast sibling tools like get_source_sheet or browse_library, so it stops just 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 three bullet modes give clear conditions for when to call the tool: pass ref for sheets using a text, pass user_id for a user's sheets, or pass neither for latest. It provides no exclusion criteria or alternative tool names, but the main use contexts are explicit.

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 read-only, open-world, idempotent, and non-destructive hints. The description adds valuable behavioral context: it explains the conditional output based on parameter presence, and mentions that it returns version titles. This exceeds what annotations alone 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?

Two concise sentences, no fluff, and the conditional logic is front-loaded. Every word contributes to understanding usage.

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 listing tool with one optional parameter, the description covers both output modes and gives concrete language examples. No missing information seems necessary for an agent 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?

The description fully explains the single optional parameter `language`, detailing both its omission and its use, including specific examples. Since schema coverage is 0%, this compensation is essential and well-executed.

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 dual function: without a language parameter it lists all language codes, and with one it lists translated books for that language. This is a specific verb+resource formulation that distinguishes it from sibling tools like list_book_titles or get_text_versions.

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 explicit context for two usage scenarios (with/without language code) and provides example codes. However, it does not name alternative tools or state when not to use it, so it lacks explicit exclusions or comparisons.

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 this read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that the tool returns canonical forms, book, structure, and previous/next sections, which is useful output context, but it doesn't disclose behavior on invalid input (e.g., failure modes, acceptable formats, or whether it throws errors). No contradiction with annotations exists.

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 29-word sentence with the verb pair front-loaded and the output components listed after a colon. Every phrase contributes either the action or the return content; there is no filler or repetition of the title.

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 one required parameter, no output schema, and annotations covering safety, the description delivers the core contract and enumerates return fields. However, 'its structure' and 'previous/next sections' are undefined, and there's no treatment of error conditions or example references, leaving some ambiguity for an agent calling the 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?

With 0% schema description coverage, the description must carry the meaning of 'ref.' It does so by calling it 'a text reference' and describing what normalization yields, but it stops short of providing accepted formats, syntax examples, or edge-case behavior. For a single-parameter tool, this is a basic adequate semantic but not a rich one.

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 opens with 'Validate and normalize' – a specific verb-resource pairing targeting text references. It then enumerates distinct outputs (canonical English/Hebrew forms, book, structure, previous/next sections), which clearly distinguishes it from sibling tools like find_references_in_text (which extracts refs from free text) and resolve_name (which resolves names).

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 – you have a reference string and need validation/normalization – but it never explicitly states when to choose this over siblings, nor does it name alternatives or exclusions. No comparison to find_references_in_text or resolve_name is provided, so the agent must infer the right context from the verb and output list alone.

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 already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful context about the composition of the returned pack, but it does not disclose behavioral nuances such as how conflicts between date and parasha are resolved or what happens when requested content is unavailable.

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 well-organized sentence followed by a short use-case clause. The colon-delimited list packs a lot of content without rambling, and every phrase contributes to explaining what the tool provides.

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 there is no output schema, the description does a decent job enumerating the returned components. Still, it is vague about the shape of the response, the interaction between parameters, and the meaning of 'everything,' so an agent would not fully anticipate the result structure before calling.

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?

With only 43% schema coverage, the description partially compensates by clarifying that the reading can be requested by date or parsha name, and that the commentary relates to a chosen aliyah's opening verses. However, it does not explain the israel or vowels parameters, leaving meaningful gaps for a 7-parameter tool.

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 names a specific deliverable, a weekly Torah portion study pack, and enumerates its contents: the reading, aliyot, haftarah, selected aliyah text, commentary, and themes. This distinguishes it from the sibling get_parasha or get_torah_reading, though it does not explicitly name them.

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 phrase 'Great for preparing a dvar Torah' gives a clear use case, implying this is the comprehensive study tool. However, it does not explicitly state when to prefer this over related tools like get_parasha or get_torah_reading, nor does it mention any exclusions or alternatives.

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, idempotentHint, and non-destructive, so safety is covered. The description adds no further behavioral detail—no mention of return format, pagination, rate limits, or authentication. It's adequate but doesn't go beyond the annotations in any meaningful way.

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, efficient sentence that front-loads the purpose and includes helpful examples. No wasted words, and it reads naturally.

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 is simple (one array parameter), and annotations cover safety. However, the description lacks the precise format for 'refs' and doesn't explain what the output will look like (though no output schema is given). For a simple recommendation tool, this is moderately complete but leaves a key detail ambiguous.

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% for the sole parameter 'refs', so the description must compensate. It hints that refs are passage references ('one or more passages', 'set of verses') but doesn't specify the expected format (e.g., 'Genesis 1:1' or Sefaria reference conventions). This is a significant gap for correct invocation.

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 recommends topics relevant to passages, with a specific verb and resource. It gives concrete examples (tagging source sheets, finding themes) that help an agent understand the purpose. It doesn't explicitly differentiate from siblings like search_topics or get_topic, but the unique angle (topics for passages) is clear enough.

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 use cases through examples ('for tagging a source sheet or finding themes in a set of verses') but doesn't explicitly state when to prefer this over alternatives like search_topics or get_topic. There's no explicit exclusion or comparison to siblings, so an agent must infer the appropriate context.

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 this is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those hints by explaining that the tool handles fuzzy, transliterated, and Hebrew input and that it returns validity information and canonical names. No contradiction with 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, no filler, with the core purpose first and parenthetical examples that illustrate rather than distract. 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?

Given there is no output schema, the description still communicates the key return information the agent needs: validation status and canonical names. It does not detail result shapes or how the 'limit' interacts with results, but those are largely inferable from the schema and the described behavior.

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 only 33%, with only the 'type' parameter documented. The description compensates for the ambiguous 'name' parameter by showing example inputs and describing what kinds of names are accepted, while 'limit' and 'type' are sufficiently defined by their schema constraints.

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 states a clear action (autocomplete and identify), the resource types (book title, reference, author, topic, person), and the outcome (validity check plus canonical names). It is specific and easy to parse, though it does not explicitly differentiate itself from sibling tools like parse_reference or dictionary_autocomplete.

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 input is partial, misspelled, transliterated, or Hebrew. However, it never names alternatives or says when not to use it, so an agent must infer the distinction from sibling names rather than being given explicit guidance.

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, openWorldHint, and idempotentHint. The description adds meaningful behavioral detail beyond that: it specifies the return structure (matching references, highlighted snippets, total hit count, category breakdown), explains lemmatized vs. exact matching, and mentions pagination via offset. This is useful context the agent cannot get from the schema alone.

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 efficiently structured: the first line states the core purpose, followed by concise bullet-like points for exact, filters, sort, and return behavior. It is front-loaded, avoids redundancy, and every sentence conveys actionable information. There is no filler.

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 complexity (8 parameters, 2 enums, no output schema), the description is remarkably complete. It covers search scope (texts vs sheets), language, matching, filtering, sorting, pagination, and return content including how to use the category breakdown. It omits only trivial details like size limits, which are already in the schema. Nothing essential is missing for an agent to correctly invoke the 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?

Schema coverage is only 25% (just slop and filters have descriptions). The description compensates by explaining the purpose of exact, filters, sort, search_in, and offset (via 'paginate with offset'). It does not explain size or slop, but slop already has a schema description and size is a simple integer with defaults. Overall, the description adds substantial meaning to parameters whose semantics are otherwise not documented.

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 states a specific action (full-text search) over a clear resource (the entire Jewish library or user-made source sheets), and mentions support for Hebrew or English queries. This clearly distinguishes it from sibling tools like search_topics, which search topics rather than full text, and from browse_library, which is for browsing.

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 practical usage detail: how to narrow by category/book path, how to control matching with exact, and how to sort by relevance or chronological. It also tells the agent to use the category breakdown to refine filters. It doesn't explicitly contrast with alternative search tools, but the domain is clear enough that an agent can infer when to use this tool.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context: without a filter it returns 'the most prominent topics' and the filter applies to a word in the title. It does not contradict the 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?

The description is a single front-loaded sentence with no filler. It conveys the core action, the optional filter, and the default behavior efficiently.

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 low-complexity read-only listing tool with rich annotations and schema defaults, the description covers the key semantics. Some ambiguity remains around matching behavior (substring vs exact word) and what 'prominent' means, but the description is adequate for a list operation 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 0%, so the description must compensate. It explains that 'contains' means a word in the title, but it does not describe the 'limit' parameter, leaving that to the schema's default and constraints. Partial semantic coverage for two 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 states a specific verb and resource ('List topics') and adds a concrete filtering criterion ('filtered by a word in the title'), plus the unfiltered default behavior. This clearly distinguishes it from sibling tools like get_topic or search_library.

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 it: to list topics, optionally narrowed by a title word. However, it does not explicitly mention alternatives or when not to use this tool, despite many related siblings such as get_topic, recommend_topics, and search_library.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds content details (what the briefing includes) but no further behavioral traits such as defaults, error handling, or data sources.

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?

One dense, front-loaded sentence that lists all key output elements without fluff. Every phrase earns its place, making the tool easy to scan and understand.

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 no output schema, the description sufficiently enumerates the returned content, and the input schema documents defaults for date and location. It could mention output formatting or behavior when no location is given, but the current level is adequate for an agent 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?

Schema description coverage is 71%, so the schema handles most parameters. The description mentions candle-lighting and havdalah times, which relate to candle_minutes and havdalah_minutes, but does not add meaning to those two undocumented parameters; it adds little 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 states a specific resource ('a ready-to-read Friday summary for a location') and enumerates its components (candle-lighting, havdalah, parsha, haftarah, verse, holiday). This clearly differentiates it from sibling tools like get_shabbat_times or get_parasha, which cover only one piece.

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: it is a consolidated Friday briefing for a location. It does not explicitly name alternatives or state when not to use it, but the bundled nature of the output makes its use case evident.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds useful context by specifying that it returns exact references and optionally opening lines, and lists content categories. It does not contradict annotations and enriches behavioral understanding beyond the safety profile.

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 sentence that front-loads the key value proposition ('One-call daily briefing') and then enumerates the included content. It is concise, well-structured, and free of filler. Every element serves to clarify what the tool does.

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 composite tool with no output schema, the description lists the return content but does not specify the output format (e.g., text vs. JSON) or address edge cases like how the date parameter interacts with 'today', or how the israel flag affects results. It covers the main content categories but lacks depth on output structure and parameter effects. Given the tool's complexity, more detail would improve completeness.

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 only 40% (only 'only' and 'include_opening_text' have descriptions). The description mentions 'Optionally include the opening lines' which aligns with include_opening_text, but it does not explain the date format, timezone, israel, or the 'only' filter. Since schema coverage is low, the description fails to compensate by clarifying parameter meanings. It adds minimal value 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 clearly states the tool provides a 'One-call daily briefing' with specific content: today's Hebrew date, holidays/events, the weekly parsha, and daily learning schedules with exact references. It distinguishes from siblings like get_jewish_calendar or get_parasha by aggregating multiple elements into one call. The verb 'briefing' and resource 'Jewish time & learning' are specific and unambiguous.

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 a consolidated daily briefing but does not explicitly say when to use this instead of more specific tools like get_jewish_calendar or get_learning_schedules. It mentions 'One-call' but offers no exclusions or alternative routing. Usage is implied rather than stated, leaving an agent to infer when this aggregation is preferred.

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