TheWholeTorah

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

Even with readOnlyHint=true already declared, the description adds meaningful behavioral context: answers are grounded exclusively in internal lessons/sources, citations are included, and the tool will state when it does not know rather than guess. This goes 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?

Three tight sentences: the first states the core function and grounding constraint, the second discloses the honesty behavior, and the third gives a usage cue. No redundant wording; 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?

With no output schema, the description covers the key expectations: an answer with citations, grounding limits, and refusal to guess. Combined with parameter documentation, an agent has enough to invoke the tool correctly. A slightly fuller description of output format would push this to 5, but it is not a significant 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 description coverage is 100%, and the schema already explains both parameters clearly. The description does not add new parameter-level semantics beyond what the schema states, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('ask'), the resource (a grounded Torah question), and the unique behavior: answers are grounded ONLY in TheWholeTorah.ai's own lessons and sources, with citations. This distinguishes it from the sibling retrieval/search tools without requiring the agent to open their schemas.

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 recommends this tool for 'what does X say about Y' questions, giving the agent a clear selection heuristic. It stops short of naming specific when-not-to-use cases or alternative tools, but the preference signal is strong 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?

The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral detail: output is limited to published recordings, returns one MP3 URL per language, and serves an audio-listening purpose, which goes beyond the 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 a single, well-structured sentence that front-loads the core purpose ('Narration links for a lesson by slug') and then efficiently adds the key output constraint. No wasted words.

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 no output schema, the description provides enough context: what is returned, for which languages, and why it matters. The slug source is covered by the schema description, so no critical information 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?

Schema description coverage is 100% and the only parameter, slug, is already clearly documented as coming from search_lessons or get_daily. The description reinforces that the slug identifies the lesson but does not add meaning beyond the schema's parameter documentation.

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 (lesson audio narration links) and the key behavior (one MP3 URL per language with a published recording). It distinguishes the tool from text-focused siblings by noting the lesson can be listened to, not just read, though it does not explicitly name an alternative.

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 'so the lesson can be listened to, not just read' implies when audio is needed versus reading the lesson, but it does not explicitly state when to use this tool over get_lesson or get_source_text, nor does it provide exclusions.

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

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

The annotation already communicates readOnlyHint=true, so the main risk is handled. The description adds valuable behavioral context beyond that: the Jewish day starts at nightfall, so after dark the next day's entry applies. This is a genuine behavioral disclosure not present in the schema.

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?

Three short sentences, each earning its place: one for the core action, one for domain context, and one for a critical temporal caveat. The most important operational note is front-loaded and 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?

For a read-only, no-required-parameter lookup tool with fully documented schema fields, the description covers the essential selection and invocation knowledge: what it returns, what the default is, and the one behavior that could surprise an agent (nightfall boundary). No output schema exists, but 'one short entry per Hebrew calendar day' sufficiently signals the return nature.

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 adds meaningful semantic value by clarifying that the date is a civil date and by explaining how the Hebrew-calendar day boundary (nightfall) affects which entry is returned, going beyond the schema's 'YYYY-MM-DD' hint.

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 resource ('the Hayom Yom entry') and a clear operation ('get for a civil date'), then explains what Hayom Yom is. This uniquely distinguishes it from siblings like get_lesson or get_source_text, which target different content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: the tool is for retrieving a specific daily Chassidus entry, with a civil date and a Jerusalem default. It does not explicitly name alternatives or say when not to use it, but the context is strong enough to guide 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 declare readOnlyHint=true, so the safety profile is covered. The description adds useful shape information — two distinct response modes depending on the concept parameter, and that cards come back as excerpts with a link — but says nothing about missing keys, unknown slugs, or result size.

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 dense sentences with no filler; the primary fetch is front-loaded and the conditional concept mode follows. The clause "what the term means, what it does in this maamar, and the deeper point" is a slightly listy run-on but each element carries information about the return value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey return values and does: parts, concept cards, and the excerpt-plus-link card payload. For a read-only lookup with fully documented parameters, the remaining gap (what a "part" looks like, error behavior) 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 100%, so the baseline is 3, but the description goes beyond it: it identifies book and maamar as keys sourced from list_in_depth, and it explains what supplying a concept key actually yields rather than merely calling it "optional". The language fallback behavior is left entirely to 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 (one In Depth maamar identified by book + maamar slug) and what it returns (its parts and concept cards), plus the conditional mode when a concept key is supplied. It routes the agent to list_in_depth for the keys, though it does not distinguish itself from get_topic, which also deals with concepts.

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?

"from list_in_depth" tells the agent where the required keys come from, and "With a concept key, that card" clearly states the optional second mode. There is no explicit when-not-to-use guidance or named alternative for retrieving a concept outside a specific maamar (e.g. get_topic).

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, and the description adds valuable context about the response shape: the lesson opening is returned in full, with a link for the rest. This goes 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 sentences, no filler, with the core action and the most important return detail front-loaded. 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 single-parameter read-only tool, the description, schema, and annotations together provide everything needed: the parameter source, the action, and the shape of the response. No critical information 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?

Schema coverage is 100% for the slug parameter, so the baseline is 3. The description adds value by stating the slug comes from search_lessons, clarifying how to obtain a valid parameter value.

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 fetches one lesson by slug and specifies the source of that slug (search_lessons). It distinguishes itself from sibling tools like search_lessons and get_daily by describing exactly what is returned.

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 says the slug comes from search_lessons, which gives the agent a clear usage workflow. It does not exhaustively list alternatives or exclusions, but the context is sufficient for correct selection among the given siblings.

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 mark readOnlyHint=true, so the safety profile is covered. The description adds useful context: the text is public-domain via Sefaria, vocalized, and returned in full. It does not disclose failure behavior or payload size, but for a read-only fetch that is acceptable.

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, with the core action and scope in the first sentence and licensing context in the second. Every word contributes; no fluff 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?

For a simple one-parameter read-only tool with no output schema, the description fully covers what is returned (full vocalized classical text) and its provenance (Sefaria public domain). Nothing essential is missing 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?

Schema coverage is 100%, so the single parameter 'slug' is already documented clearly. The description reinforces the concept of a 'lesson' but adds no new parameter-level detail, matching the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'fetch,' the resource ('classical source text a lesson is built on'), and even names example texts (Mishnah, Shulchan Aruch, Tanya). This distinguishes it from siblings like get_lesson or get_audio without needing to inspect their schemas.

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 usage is implied: if you need the full source text underlying a lesson, this is the tool. However, there is no explicit guidance on when not to use it or which alternative to choose (e.g., search_sources, get_lesson), so the agent must infer the boundary from sibling names.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description adds the substantive part: exactly what is aggregated and returned, including that cards and lessons carry links and passages carry book/page/short excerpt. It does not address failure behavior for a missing slug, which is the main remaining gap for a lookup 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?

It is a single front-loaded sentence that leads with the resource and then lists the returned components, with no filler. The enumeration is dense but each clause maps to a distinct part of the response, so nothing is wasted; a slightly shorter formulation would read better.

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, and the description compensates by describing the returned structure component by component, which is exactly what an agent needs to decide to call it and to consume the result. Combined with 100% schema coverage and a clear read-only annotation, nothing essential is missing for a two-parameter lookup 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 100%, so the schema already documents both parameters, making 3 the baseline. The description adds real meaning beyond it by disclosing that the slug accepts an alias (e.g. 'bitul'), which the schema does not state; it is silent on the language parameter, but the schema fully enumerates its values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (a single topic) and enumerates its result composition: name/description, Chassidut In Depth concept cards with links, closest passages in Sefer HaMaamarim with book/page/excerpt, and central lessons with links. This clearly separates it from list_topics (enumeration) and the single-item getters like get_lesson or get_in_depth.

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?

Usage is only implied: by describing an aggregate hub of cards, passages and lessons, an agent can infer this is the entry point for exploring a topic. There is no explicit when-to-use statement, no mention of when to prefer get_in_depth, get_lesson or search_lessons instead, and no guidance on what happens with an unknown slug.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds that this returns a catalog of the entire library. However, it does not disclose response shape, pagination, ordering, or any other behavioral details beyond being a read-only listing.

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 short sentences carry the full meaning: the first defines what the tool returns, and the second gives the intended use. There is no filler or redundant restating 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?

For a zero-parameter read-only listing tool, the description is nearly complete: it conveys scope, contents, and when to use it. The only gap is the absence of an output schema or any statement about the exact response structure, but that is a minor concern for such a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema covers 100% of them, so the baseline is 4. The description reinforces that the tool returns the full catalog by saying 'every book and collection,' which adds mild extra meaning over the empty 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 identifies the resource ('every book and collection on TheWholeTorah.ai') and the included details ('sections and published lesson counts'). It also distinguishes the tool from search tools by positioning it as a catalog to consult before searching.

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 to use it 'to see what the library covers before searching,' which gives clear context for when to call it. It does not explicitly name alternatives like search_lessons or search_sources, but the 'before searching' phrase implies 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=true, so the safety profile is covered. The description adds useful context about what each item contains (link, segments, concept cards), but does not disclose ordering, total count, or whether it returns all maamarim, which would be helpful since there is no output schema.

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, information-dense sentence with a parenthetical clarification. It is concise and front-loads the content scope, though it could be slightly clearer by explicitly stating the list action at the start.

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 list tool with no output schema, the description is largely complete: it names the source collection and specifies the components of each item. It stops short of describing the return format (e.g., array, pagination) but that is a minor gap given the tool's simplicity.

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. The description does not need to compensate for any schema coverage gap, as there are no parameters to describe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the specific resource (maamarim explained in Chassidut In Depth) and its scope (Sefer HaMaamarim 5659 so far), and implies a list of items each with link, segments, and concept cards. It does not use an explicit verb like 'list' but the name and title together make the action clear, and it distinguishes from the sibling get_in_depth 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 offers no guidance on when to use this tool versus alternatives such as get_in_depth or search_lessons. It simply states what the content is, leaving the agent to infer that this is a browsing/list operation with no parameters.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value by disclosing the return contents (lesson counts and concept-card counts per topic) and implying a complete, unpaginated enumeration via "Every topic." Ordering of results is the only unstated behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler: the first front-loads scope and return content, the second delivers the routing instruction. The example terms are useful matching aids rather than padding.

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 parameterless read-only list tool with no output schema, everything an agent needs is present: what's listed, what each entry carries, and the follow-up call to make. Only minor gaps remain, such as result ordering or a description of the slug format.

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 takes zero parameters, so there is no parameter semantics to compensate for; baseline is 4. Nothing in the description conflicts with the empty 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?

States a specific verb+resource ("Every topic (concept) on TheWholeTorah.ai") and enumerates what each entry contains: lesson count and Chassidut In Depth concept-card count. Concrete domain examples (bittul, tzimtzum, teshuvah) make the scope unambiguous and separate it from list_books/list_in_depth.

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?

Explicitly routes the agent: "Use it to find a topic's slug for get_topic." This makes the list-then-detail workflow clear. It stops short of stating when not to use it, but the alternative (get_topic) is named with the condition that selects it.

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

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

With readOnlyHint=true, the safety profile is already covered by annotations. The description adds useful behavioral context beyond that: it returns titles, links and short excerpts, and spans multiple Torah text categories, which helps set expectations for output shape and 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?

Three short sentences, each adding distinct value: action/scope, return shape, and usage sequencing. No filler or repetition of schema details.

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 search tool with fully described parameters and no output schema, the description covers what the tool searches, what it returns, and how to follow up. Nothing essential for correct invocation 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?

Schema description coverage is 100%: both query and limit are already documented in the input schema. The description's mention of 'in any language' is effectively redundant with the schema's query description, so it adds little parameter-level meaning beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search'), names the resource (TheWholeTorah.ai), and defines scope (lessons across Mishnah, Tanya, Hayom Yom and Chassidus). It also references get_lesson, distinguishing discovery from retrieval.

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 usage context: 'Use this first to find what exists, then get_lesson for one.' This explicitly sequences the tool against a sibling, but it does not mention when to prefer search_sources or other alternatives, so it stops short of full when/when-not 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 declare readOnlyHint=true, and the description adds behavior beyond that: it is a 'hybrid search' and it 'returns labeled passages with links where available.' This gives the agent useful expectations about result shape and source-material behavior without contradicting the 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?

Three compact sentences, each earning its place: the first defines scope, the second describes output behavior, and the third routes to the correct sibling. The key 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 read-only search tool with two fully documented parameters, the description covers scope, output ('labeled passages with links'), and sibling differentiation. No output schema exists, but the description sketches the return value adequately.

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 schema already documents both parameters fully. The description does not add new parameter-level meaning beyond the schema, which aligns with the baseline expectation.

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 verb ('search') and a distinct resource ('classical text corpora themselves'), and enumerates the corpora (Mishnah, Talmud, Rashi, Rambam, Shulchan Aruch, Tanya, commentaries). It explicitly distinguishes itself from lessons, separating it from the sibling search_lessons even before that sibling is named.

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 routing guidance: 'Use search_lessons for our teaching; use this for the primary texts.' This states both when to use this tool and when to prefer an alternative, leaving no inference required.

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