Bereishes

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by stating that results are in each commentator's own words and include links, which is not captured in the annotations or 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 two efficient sentences, front-loading the return value before the narrowing option. There is no redundant or filler text.

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 fully described parameters and clear annotations, the description provides enough to call it correctly and understand the returned commentary format. The main missing piece is comparative guidance against sibling tools, which is a usage concern rather than a basic invocation 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%, so all three parameters are already documented in the input schema. The description's phrase 'Can be limited to named commentators' mirrors the commentators parameter but adds no syntax or meaning 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 gives a specific verb and resource: it returns commentary on a verse or passage, naming representative commentators. It is clear what the tool does, but it does not explicitly differentiate itself from siblings like fetch_text or semantic_search.

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

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

The description explains what the tool returns and that results can be limited to named commentators, but it gives no guidance on when to use this tool instead of fetch_text, resolve_ref, or semantic_search. Usage is only implied by the purpose statement.

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 openWorldHint=false, so safety is covered. The description still adds real behavioral detail those annotations cannot convey: per-language truncation at roughly 3000 characters for a single ref and 1500 for multi-ref reads, with an explicit [TRUNCATED] marker in the output.

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: capability first, range syntax second, truncation limits last. Every clause carries information an agent would otherwise have to discover by trial, and nothing is repeated from 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 two-parameter read tool with no output schema, the description covers the input modes, the batching limit, the accepted ref syntax, and the one surprising return behavior (truncation). An agent can call it correctly and interpret the response without further guessing.

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 two parameters are already documented, including the max-10 limit on refs and that it substitutes for ref. The description adds value on top by showing that a range form such as 'Shabbat 21b:5-11' is accepted, which the schema's examples do not demonstrate.

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: returns full Hebrew and English text of one canonical ref or up to 10 refs, with links. The scope (canonical refs, bilingual text) separates it conceptually from fetch_commentary, though no sibling is named explicitly.

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 (you already have a canonical ref) and gives a practical constraint of up to 10 refs. It never states the when-not case or points to resolve_ref for normalizing a non-canonical reference or to semantic_search when the ref is unknown, so routing is left 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 declare readOnly/openWorld=false, so safety carries little burden. The description adds real behavioral context beyond them: the tool either succeeds to a canonical ref or returns suggested completions, disclosing a partial-success mode an agent must be prepared to handle.

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 the examples placed where they help most and no filler. Nothing is repeated from the schema or 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 one-parameter lookup with no output schema, the description covers the essential return behavior (canonical ref vs. suggestions). Slightly thin on what the agent should do after receiving suggestions, which matters because there is no output schema to clarify the shape.

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?

Only one parameter and schema coverage is 100%, so the schema already documents `query` fully. The parenthetical examples ('Rambam Teshuvah 2', 'Hilchot Shabbat ch. 5') add useful form guidance about what a valid reference looks like, but no detail on ambiguity, transliteration, or abbreviation handling.

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?

Specific verb+resource: turns a natural-language reference into the library's canonical ref, with two concrete examples that make the input shape unambiguous. It is clearly distinct from fetch_text/fetch_commentary by name, but it never explicitly contrasts itself with semantic_search, which is the closest sibling in intent.

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 implied rather than stated: the agent can infer this is the normalization step before a fetch, and that unresolved input yields suggestions. There is no explicit 'use this when X, use semantic_search when Y', and no guidance on what to do with the suggested completions.

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, non-destructive, closed-world, but the description adds genuinely useful behavioral detail: results are ranked, each carries a ref plus roughly the first 180 characters and a link, and snippets are explicitly flagged as short excerpts rather than full passages. That caveat prevents a common misuse, though pagination/limit behavior is left to 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?

Four short sentences, purpose first, then return shape, then the snippet-length caveat, then the optional ranking input. Nothing is repeated and every sentence carries information an agent would otherwise have to discover by calling.

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 carries the burden of describing results — and it does: ranked snippets, the ref, the ~180-character excerpt, and links. Combined with full schema coverage on the inputs, an agent has everything needed to call and interpret the result.

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 query, limit, ref_prefix and hebrew_terms in detail. The only elaboration is that hebrew_terms boosts ranking of passages containing those words, which largely restates the schema field description. Baseline 3 applies.

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 ('Searches the library by meaning'), and 'by meaning' distinguishes it from exact-ref lookups such as fetch_text/resolve_ref without naming them. It stops short of explicitly differentiating from the siblings, so it is clear but not fully self-routing.

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 implied: this is the tool for topical/conceptual queries where you lack a ref. There is no explicit 'use this instead of fetch_text when…' or statement of when-not to use it, so the agent must infer routing from the sibling names and the ref_prefix parameter.

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