Source Library

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by detailing language handling, multi-work volume logic, edition behavior, and special statuses like 'insufficient-heads' and absent work_language, providing substantial behavioral context not present in 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 long but well-structured with clear section headers (LANGUAGE, MULTI-WORK VOLUMES, EDITIONS) and front-loads the most critical 'START HERE' directive. Some redundancy exists, but each section earns its place given the tool's complexity.

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 provided, the description fully compensates by covering return content, edge cases (translations, insufficient heads), and cross-referencing sibling tools. It leaves no obvious gap for the agent to understand when and how to use the tool and interpret its 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?

The schema has 100% coverage (book_id is described), so the baseline is 3. The description does not add any meaning beyond the schema for this single parameter; it mentions 'lang' for other methods but not for book_id itself. No extra semantics are introduced.

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 tool as the read-only step 1 of the pipeline, specifies the exact resources returned (summary, chapter list, edition metadata, DOI, etc.), and differentiates it from siblings like get_book_text and search_within_book by explicitly naming them and their roles.

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 when-to-use guidance ('START HERE'), names alternatives ('Use list_editions', 'Then: get_book_text ... step 2', 'get_quote ... step 3'), and explains when language nuance matters, covering exclusions and next steps.

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?

Massive behavioral context beyond annotations: truncation semantics, truncated flag, truncation_note for resuming, daily page budgets, auth tiers, per-page language fallback behavior, and the explicit warning not to infer end-of-book from pages_returned. Annotations already mark readOnly/idempotent, and the description adds significant operational detail.

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 long but well-structured into pipeline, truncation, budget, and scope sections. Every sentence provides actionable information; no filler. Slightly dense, but the tool's complexity and the absence of an output schema justify the length.

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 8-parameter read tool with no output schema, the description covers return signals (truncated, truncation_note, lang_coverage, page markers), usage patterns, budget limits, and authentication paths. Nothing critical an agent needs to call this correctly 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 covers 100% of parameters, so the baseline is 3. The description adds semantic value by recommending chapter over from/to, explaining truncation_note supplies next from/to values, and clarifying language resolution behavior. This goes beyond the schema descriptions, though the schema already carries substantial per-parameter meaning.

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 clearly states the action ('Read a book's text') and places it in the READ PIPELINE as step 2, distinguishing it from get_book (step 1) and get_quote/get_quotes (step 3). The verb+resource+stage 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?

Provides explicit guidance: call get_book first, prefer chapter over from/to, use get_quote/get_quotes for citations, and use the dataset API for corpus-scale text. This gives an agent clear decision rules for when to use this tool versus 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, but the description adds substantial behavioral detail beyond that: it explains that witnesses are only returned when the reference is printed on the leaf, that nothing is interpolated, that empty results mean no anchored leaf exists (not that the citation is wrong), and that line numbers are not resolved. It also discloses edge cases like shared pages and bare-number ambiguity across systems. 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?

Though lengthy, every sentence adds value. The description is front-loaded with the core purpose, then usage, return values, limitations, and edge cases in a logical flow. It avoids fluff and uses plain-language warnings (e.g., 'LIMITS, stated plainly'). The structure is coherent despite being a single block of 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?

With no output schema, the description must explain return values, and it does: it describes the Greek reference edition, English translation, scan page, reader URL, and quote_api link. It also covers behaviors like editions_searched and other_works_at_this_reference. Given the tool's complexity (two citation systems, edge cases, follow-up calls), the description is complete enough for an agent to select and 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 baseline is 3, but the description enriches the parameters significantly. It explains why 'work' is required for Stephanus numbers (they restart per volume) and that omitting it yields candidate dialogues. For 'system', it warns not to guess it from the number since ranges overlap. For 'reference', it clarifies accepted formats and the ambiguity of bare numbers. This adds meaning well beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Turn a CANONICAL CITATION into the actual leaves that carry it.' It clearly distinguishes itself from page-based lookup tools and explicitly names the citation systems (Bekker/Stephanus). It also differentiates from get_quote by explaining the tool's output is leaves, not verbatim text.

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

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

The description provides explicit when-to-use guidance: 'USE THIS FIRST whenever a passage arrives as a canonical reference rather than a page' and warns against deriving the page manually. It also gives a clear follow-up action: 'Then call get_quote with the returned book_id + page.' It mentions exclusions (e.g., line numbers are not resolved) and how to avoid misinterpretation (read other_works_at_this_reference), satisfying the highest bar.

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 destructiveHint=false, so the safety profile is already covered. The description adds rich behavioral context beyond annotations: the response headline is citation_link which must be presented to the user; page-break continuity behavior (nearly 1-in-5 boundaries have running sentences); non-Latin script romanization behavior ('AI-generated reading apparatus... never quote from romanized'); English-original behavior (text_source: "ocr_original", period spelling, long-s); and translated-edition attribution chain (text_source branching instruction). 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 long but every sentence earns its place — it covers five distinct operational concerns (render format, page breaks, non-Latin scripts, English originals, translated editions) each in labeled sections. Front-loaded with the purpose and the critical 'ALWAYS use before putting text in quotation marks.' The render template communicates the output format more efficiently than prose could.

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, the description fully covers return values (citation_link, text, translation, original, romanized, translation_note, transcription_note, text_source, lang_note, continues_on_next, continues_from_previous), edge cases (running sentences, non-Latin scripts, English originals, translator attribution), and operational patterns (context: true, list_editions, get_quotes). Highly complete for a complex retrieval tool with 5 parameters and no 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 coverage is 100% and the description adds substantial meaning to each parameter beyond the schema. The lang parameter gets the crucial caveat that 'quote.lang on every response says which edition was actually served' and that a fallback to English must not be presented as the requested edition. context gets the 'sentence spanning the page break' motivation. include_image gets user-benefit criteria (illustrated leaf, title page, diagram, disputed OCR). page and book_id are self-evident.

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 'READ PIPELINE step 3 — CITE. Get the exact verbatim text of a single page plus its citation apparatus.' This is a specific verb+resource+scope statement. It distinguishes from siblings by explicitly naming get_quotes ('For several pages of one book at once, use get_quotes.') and by its focus on citation apparatus, which search_within_book and get_book_text do not provide.

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?

Exceptionally explicit. States 'ALWAYS use before putting text in quotation marks.' Gives conditional guidance: 'if continues_on_next or continues_from_previous is true, call again with context: true.' Recommends list_editions for translated editions when original-language witness needed, and get_quotes for multi-page needs. Also tells the agent when NOT to use it (English originals don't need translation handling).

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?

An annotation already provides readOnlyHint and idempotentHint, but the description goes well beyond that by disclosing romanized-layer behavior, text_source semantics, mixed-edition handling, daily page-budget impact, and include_image's first-5-pages inline behavior. These are non-obvious behaviors an agent needs to know before calling the 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?

The description is dense but every sentence carries load: purpose, invocation modes, limits, return-entry fields, edge cases, and budget/API exclusions. It is front-loaded with the core purpose and uses concrete examples like [12, 40, 41] without 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?

With no output schema, the description takes on the burden of explaining return behavior, and it does: citation_link, romanized layer, text_source, quote.lang, and page_image_url are all named. It also covers mixed batch composition, daily budget, and the boundary against the dataset API, so an agent has enough context to invoke 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?

Although schema coverage is 100%, the description adds essential semantics not in the schema: pages is an alternative to from/to rather than additive, the 25-page maximum, per-page language resolution requiring the agent to read quote.lang, and concrete include_image behavior with inline image blocks versus page_image_url. This meaningfully improves parameter understanding.

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 verbatim text + citation_link for SEVERAL pages of a single book in one round-trip.' It clearly identifies the batch nature of the tool, distinguishing it from the singular sibling get_quote, and places it in context as 'READ PIPELINE step 3 — CITE.'

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 when to use it: to assemble a multi-passage dossier from several pages, with explicit page/range specification and a 25-page cap. It also excludes corpus-scale extraction by directing that to the dataset API. However, it does not explicitly say 'use get_quote for a single quote,' leaving that particular alternative 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description isn't credited for the safety profile. However, it adds genuine behavioral context BEYOND the annotations: the return shape ('title, author, language, year, and translation progress') and a clear negative scope ('no content/topic matching'). The 'no content matching' constraint is exactly the kind of non-obvious behavioral trait that prevents misuse. It doesn't discuss rate limits or error behavior, but for a read-only listing tool this is strong 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?

The description is well-structured and front-loaded: it leads with the core verb+object, follows with the go/no-go guidance, then lists return fields, and ends with redirects. The use of ALL-CAPS for key terms and → arrows aids skimmability. It's on the longer side but every sentence earns its place — the alternatives list at the end, while slightly long, serves the critical function of preventing misuse. One sentence could be trimmed, but this is strong work.

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 filtering/list tool with 6 params, no output schema, and no nested objects, the description covers the essential ground: what the tool does, what it returns, when to use it, and what to use instead. The absence of an output schema means the description doesn't need to explain return values. The main gaps are minor — no note about pagination, default limit behavior beyond what's in the schema, or relationship to the similar-sounding list_editions and search_library tools. But given the schema richness on has_edition, this is a complete package for its complexity class.

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% (3 of 6 params documented), which is below the 80% high-coverage threshold. The description partially compensates by linking filter dimensions ('author/title fragment, language, category, translation recency') to the search, language, and category params, but it doesn't add meaningful new syntax, format, or relationship details beyond what's in the schema. The most interesting parameter (has_edition) carries its own detailed schema description, but the tool description itself doesn't reference it. Baseline 3 is appropriate: the schema and description together do the job, but the description doesn't go beyond the schema's 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 uses a specific verb+resource ('BROWSES/FILTERS THE CATALOG') and immediately scopes the method: 'by metadata (author/title fragment, language, category, translation recency) — no content/topic matching.' It explicitly differentiates from sibling tools by naming what it is not (no content matching) and which siblings do what it doesn't (search_library for topic search, search_translations for exact words, search_concept for meaning). This is textbook sibling differentiation.

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

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

The description gives an explicit go-signal ('PICK THIS to see WHAT EXISTS by an author or in a tradition') and then names specific alternatives with the conditions under which to choose them ('For a relevance-ranked topic search use search_library; for passages on a theme use search_translations (exact words) or search_concept (by meaning)'). This is exactly the explicit when/when-not/alternatives guidance the rubric rewards.

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 valuable context beyond annotations: for multi-volume collected works, the identifier refers to the set rather than a single text, and the response explicitly notes when this 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?

The description is front-loaded with a definition, then moves to parameter guidance, use cases, output summary, and a caveat. Every sentence earns its place, covering both what the tool does and how to use it without redundancy or fluff.

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

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

With no output schema, the description compensates by listing the returned fields per edition (language, date, page count, translation coverage). It also covers the multi-volume caveat and provides specific use cases. This makes the description functionally complete for a complex list 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 input schema already provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description adds practical guidance: book_id can be 'the id of any edition you already found' and work_id is obtainable from get_book. This enriches parameter meaning beyond the schema alone.

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 precise definition: 'Every edition of one work that the library holds — the other witnesses to the same text, across languages and centuries.' This clearly states the tool's function and distinguishes it from siblings like get_book or search_translations by focusing on editions of a single work.

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?

An explicit 'USE THIS when' section lists three concrete scenarios (checking a quotation against multiple witnesses, retrieving original-language text behind a translation, comparing passages across editions). It also references get_book for obtaining a work_id, but it does not name alternative tools to use instead or 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?

Discloses important behavior beyond annotations: 'it does NOT create a public collection instantly; a curator reviews and approves it.' This adds meaning to the non-readOnly/non-destructive flags by clarifying the asynchronous review workflow. Does not mention auth or rate limits, but the review behavior is a significant disclosure.

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 concise and front-loaded with the main purpose, then quickly covers usage and key behavior. Every sentence earns its place: purpose, id sourcing, review process, and when-to-use. 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 description covers purpose, usage triggers, id sourcing, and review behavior, which is sufficient for a proposal tool. It lacks details about what happens after approval and doesn't explain optional name/email parameters, but these are minor given the lack of an output schema and the overall clarity. The tool's complexity is moderate and the description addresses the key usage questions.

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

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

The schema covers 4 of 6 parameters (title, book_ids, rationale, suggested_slug), and the description reinforces required parameters and adds value by directing users to get book ids from search_library/list_books/get_book. However, the optional parameters 'name' and 'email' have no schema description and are not mentioned in the description, leaving a semantic gap. The description adds partial value but doesn't fully compensate for the uncovered 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 clearly states the tool's purpose: 'Propose a themed collection of books to the Source Library team' with specific components (title, rationale, book ids). It distinguishes itself from sibling tools by explicitly comparing to submit_feedback and share_findings and noting it does not create a public collection instantly.

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?

Provides explicit usage context: 'Use this when the user has identified a coherent set of books worth grouping and wants to contribute that curation back.' It also tells where to get book IDs (search_library / list_books / get_book) and notes the review process, giving clear guidance on when to apply. No explicit 'when not to use' exclusions, but the context is strong.

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 it as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: similarity calibration thresholds (0.70+ strong, 0.55-0.70 verify, below 0.55 drift), the instruction to only quote 'translation' snippets not 'summary', and the corpus indexing behavior via period translations. 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?

Though lengthy, every sentence adds value: usage alternatives, calibration thresholds, snippet-type warning, cross-cultural tips, and corpus indexing insight are all non-redundant. Structural devices like arrows and examples make it skimmable. No filler, no repetition of schema descriptions.

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 high-complexity semantic search tool with no output schema, the description is remarkably complete. It covers selection criteria, quality thresholds, return value characteristics (snippet_type), language/edition handling, and cross-cultural search strategies. All necessary decision context is provided for an agent to invoke the tool confidently.

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 covers 100% of parameters, but the description substantially enhances their meaning. It explains the purpose and nuanced usage of max_per_book ('diversify results across many books'), clarifies the 'lang' parameter's default and edition lookup, and gives concrete query examples. It transforms formal parameter definitions into actionable strategies.

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+resource: 'RETURNS QUOTABLE PASSAGES matched by MEANING.' It clearly differentiates from sibling tools by naming alternatives (search_translations for exact words, search_library for books, get_book for known authors) and provides concrete examples like 'distributed cognition' mapping to historical passages.

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?

Explicit when-to-use guidance: 'PICK THIS when the modern term won't literally appear in historical texts.' Then it states when NOT to use: 'For exact words/distinctive terms use search_translations... to list which BOOKS cover a topic use search_library; if the user named an author/work, get_book first.' This is a model of usage differentiation.

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 this read-only and idempotent, and the description adds substantial behavioral detail beyond that: the two interleaved result lanes, the gallery/render differences across hosts, public and stable image URLs, offset echo and next_offset pagination, the title_is_descriptive flag, sparse iconclass coverage, and the dirty year field on museum-artwork records. This is far more transparency than typical.

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 long but every sentence carries a distinct operational fact; there is no filler or restatement of the title. It front-loads the corpus scope and then layers filters, result behavior, and edge-case warnings in a logical order.

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 adequately documents return values and states: images.length, total, note, offset/next_offset, iconclass array, thumbnail_data_uri, inline gallery behavior, and the title_is_descriptive/source_record_title distinction. It also covers the critical empty-result and dirty-data edge cases, making it complete for a complex 12-parameter 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 75%, and the description significantly enriches the parameters: it warns that type is best-effort, that year_from/year_to are unreliable for artworks, that iconclass is prefix-matched and sparse, that book_id excludes artworks, and that include_thumbnail_base64 has a specific mode and caveat. It also covers otherwise-undescribed parameters by mentioning filtering by figure, symbol, and subject.

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 scope — 'Search 200,000+ historical illustrations... AND 24,000+ artworks' — and enumerates the exact media types covered. This distinguishes it clearly from the sibling text/book/translation search tools without needing to open the schema.

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 rich conditional guidance: when to page with offset instead of raising limit, when not to request base64 thumbnails, how to interpret an empty result under book_id, and to retry iconclass filters with a text query. It does not name sibling tools explicitly, but the search scope itself makes the target use case clear and the exclusion guidance is behaviorally specific.

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 known. The description adds useful behavioral context: it clarifies output type ('NOT passages'), mentions search fields ('titles, authors, subjects, and (as a secondary signal) translated text'), and describes pagination metadata ('total_matches... + returned... + offset'). It does not contradict annotations.

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

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

The description is front-loaded with the key message and uses visual separators (—, →) to structure alternatives. It covers purpose, alternatives, query tips, and pagination in about 100 words without fluff. Slightly dense but 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 8 parameters and no output schema, the description carries the burden of explaining return behavior. It does explain the pagination envelope and search scope, and provides explicit routing to siblings. It could mention the book object's fields (e.g., title, author) more explicitly, but given the tool's straightforward 'list of books' nature, this is adequate.

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 high (88%), so the baseline is 3. The description adds value by giving query formulation tips ('single distinctive words or short phrases work best... quoted phrases match exactly'), which go beyond the schema's query description. It also explains how offset and total_matches relate to pagination, adding semantics to the pagination 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 opens with 'RETURNS A LIST OF BOOKS (works on a topic) — NOT passages,' clearly stating the tool's verb and resource. It distinguishes itself by explicitly contrasting with search_translations and search_concept, and by stating 'PICK THIS to discover which works exist on a subject.' This is specific and differentiates from 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 description provides explicit when-to-use guidance: 'PICK THIS to discover which works exist on a subject.' It also names alternatives: 'use search_translations (exact words) or search_concept (by meaning); if the user already named an author/work, call get_book directly (or list_books to find the ID).' This is a model of usage 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 destructiveHint=false; the description reinforces this with non-mutating language ('returns', 'matched'). Critically, it discloses that 'summary' snippets are AI-generated and should not be quoted as the author's words, and that matching is literal term-based — behavioral traits beyond what annotations provide.

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

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

The description is dense but efficient, using a single block with clear 'PICK THIS' guidance and parameter tips. Slightly long for an MCP tool, but every sentence carries distinct value — no redundancy. The structure (purpose → alternatives → query tips → output semantics → cultural tip) is logical.

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 10 parameters (80% schema coverage), the description addresses the most impactful ones: query syntax, pagination via total_matches/returned/offset, edition behavior via response. It covers output types, caveats about AI summaries, and cross-cultural search strategy. The only minor gap is undocumented parameters (year_from/year_to, language filters) left to the schema alone, but this isn't a completeness failure given the description's breadth.

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 explains query semantics in depth (term-based matching, phrase vs. term behavior, language filters via languages vs exclude_languages). It documents 8 of 10 parameters, leaving only year_from/year_to without prose explanation, but these benefit from schema presence. The snippet_type distinction is a semantic gem.

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 specific purpose: returning quotable passages with page-level snippets and citation URLs matched by keyword. It explicitly differentiates from sibling tools by naming search_concept, search_library, search_within_book, and get_book with their distinct purposes, making selection criteria 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?

Provides explicit when-to-use guidance with named alternatives and exclusions (e.g., 'use search_concept if the modern word won't literally appear'), plus concrete query tips (single distinctive terms, double quotes for exact phrases) and a cross-cultural vocabulary tip. This exceeds the bar for usage 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?

Goes well beyond annotations: it reveals the hybrid search mechanism (lexical plus narrow semantic pass over top ~10), explains result scoring (score 0-1 normalised within book, found_by values with 'both' strongest), and clarifies that is_front_matter results are ordered last. Even with readOnlyHint=true, this adds rich detail about what the tool does and how it behaves.

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 more expansive than the minimal examples but every sentence is informative. It front-loads the purpose, then gives usage guidance, then result details. It is not bloated; the length is justified by the tool's complexity. Only minor trimming could make it even tighter.

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 fully covers what the tool returns (snippets with page numbers, score, found_by, is_front_matter handling) and even addresses edition behavior. It also integrates with sibling workflow (finding the book first). For a complex search tool, this is remarkably complete and self-contained.

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

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

Schema coverage is 100% with each parameter described. The description reinforces that book_id is required and mentions the lang/edition context, but it does not add new parameter-level meaning beyond the schema. Baseline 3 is appropriate since the schema already carries the burden.

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 'SEARCHES INSIDE ONE BOOK (requires book_id)', immediately stating the action and scope. It distinguishes itself from siblings by contrasting with search_concept (meaning-matching across the whole corpus) and explicitly naming the search type. This is a specific verb+resource+scope definition that leaves no ambiguity.

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?

Provides explicit when-to-use guidance: 'PICK THIS when you know the wording you are looking for, or want every page of one book mentioning a term.' It also gives a clear exclusion and alternative: 'IF YOU ARE SEARCHING FROM A PARAPHRASE... USE search_concept INSTEAD' and instructs to first find the book via search_library or search_concept before passing book_id. This is a model of usage 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?

The description reveals key behavioral details beyond the annotations: citations are references, not copied text, and the library re-renders canonical quotes to maintain authority. It also discloses that the submission goes to the team for review, which is important for setting expectations. 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 three sentences long but information-dense, with every sentence contributing to understanding the tool's purpose, citation semantics, and review process. It is front-loaded with the main action, making it 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 moderate complexity and lack of an output schema, the description covers the essential behavior, key content structure, and the review outcome. However, it does not mention the optional name/email fields, which may be relevant for user identity, and leaves some ambiguity about what happens after submission beyond the review step.

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 60% (3 of 5 params described). The description adds valuable context for the citations parameter (structure, reference-based, ordered list) and mentions the source for book_id/page, but it does not address the name and email parameters, which lack schema descriptions and are absent from the tool 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 tool shares a research dossier to the Source Library team, specifying the main components (title, optional summary, citations). It distinguishes the tool from sibling submit_feedback by describing it as a dossier-sharing action, not general feedback.

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?

Explicit 'Use this when' clause defines the exact scenario: when the user has assembled a thesis backed by passages across one or more books and wants to contribute it back. It also references submit_feedback as a similar mechanism and notes that submissions go to team review, not instant public pages.

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 indicate this is a write operation (readOnlyHint=false) but are otherwise minimal. The description adds meaningful behavioral context beyond the annotations: submissions are reviewed by humans, past duplicate proposals waste reviewer time, and specific report formats are more actionable. This helps the agent understand the real-world impact and expectations of the submission.

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 and front-loaded with the core purpose, followed by actionable guidance. Each sentence contributes useful information, though the list of past duplicate proposals (IIIF manifests, Content Search, DTS) is slightly detailed. Overall, it is efficient without being overly verbose.

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 feedback submission tool with three parameters and no output schema, the description provides sufficient context for an agent to invoke it correctly. It explains the submission target, reviewer expectations, and how to maximize usefulness. The only minor gap is the absence of explicit clarification that name and email are optional, but the schema already encodes that.

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%, so the description carries some responsibility for parameter meaning. It enriches the message parameter by specifying what content reviewers find valuable, such as noting which docs were checked and including record IDs/reproducing queries. However, it does not clarify the optional name and email parameters, which remain undocumented in both the schema and 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 tool submits feedback, bug reports, or feature requests to the Source Library team, using a specific verb and resource. It is distinct from sibling tools like search_library or propose_collection, so an agent can immediately identify its 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 gives clear context for when to use the tool: for feedback, bugs, and feature requests. It also provides concrete usage guidance—read the referenced docs before proposing new functionality, state which docs were checked, and prefer actionable bug reports with record IDs and reproducing queries. It does not explicitly contrast with sibling tools, but the context is strong.

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