Source Library

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description goes well beyond them: it discloses what categories are matched (same scan, same edition, other editions, cross-lingual titles), the verdict enum, the held_not_public behavior (counted, not described), and the limits field. This is rich behavioral context a caller could not infer from structured data.

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

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

Front-loaded with the core question and the when-to-call rule, and every sentence carries information (inputs, match scope, return fields, caveat). The single dense paragraph is longer than ideal and packs several distinct ideas without breaks, which costs a little readability.

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 return-value burden itself and does so completely: it enumerates the verdict values, confidence, matches with reasons, ids/URLs, held_not_public, and limits. Combined with the input guidance and the under-search caveat, an agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds practical combination guidance ('give a title + author (+ year if known), or a library URL') and warns that a URL-only verdict under-searches, so pass title and author too. It also restates the year's discriminating role, which is helpful framing even though the schema covers it.

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?

Opens with a specific, capitalized question ('DOES THE LIBRARY HOLD THIS WORK?') that names both the verb (check holdings) and the resource (the work), and explicitly contrasts itself with list_books and search_library. An agent can tell it apart from every sibling without opening a 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?

Gives an explicit when-to-use rule ('Call this BEFORE telling the user the library lacks a book, and before proposing one for acquisition') and explains why the obvious alternatives are insufficient (list_books matches words, search_library ranks by relevance). It also names the required input shape and the caveat about URL-only checks. Nothing 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the output mirrors start_review_shift's shape, how_to_run must be followed again, and a null page signals the book is finished. It is slightly indirect by deferring detail to start_review_shift rather than restating it.

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?

Front-loads the purpose in the first clause, then layers invocation timing, parameter sourcing, and termination handling in minimal sentences. Every sentence carries distinct information with no 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?

With no output schema, the description correctly covers the return contract by pointing to start_review_shift's shape and its how_to_run guidance, and it documents the null-page terminal state. The only shortfall is reliance on another tool's description for return detail rather than being 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 67%: 'book' and 'after' are documented in the schema, and the description usefully ties them to 'next.book'/'next.after from the previous page', clarifying the chained-call dependency. However, 'volunteer_code' is left unexplained in both schema and description, so the description only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Next page of the book being reviewed') and implicitly distinguishes itself from start_review_shift by being the continuation rather than the initiation. An agent can tell which of the two review tools to call without opening either 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?

Explicit timing is given: call it straight after finishing a page until the user's chosen stretch is done, and again on request. It also names the terminal branch — when page is null, offer start_review_shift with new_book true — so the when-to-stop condition and the alternative tool are both spelled out.

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 only cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial non-obvious behavior: `text_role` semantics, the meaning of an absent `work_language` (not-recorded, not 'same as edition'), the `contains_works`/`insufficient-heads` behavior for multi-work volumes, and the `editions` language codes. This is exactly the kind of interpretive context annotations cannot carry.

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?

Front-loaded with the pipeline role and well-organized under labeled sections (LANGUAGE, MULTI-WORK VOLUMES, EDITIONS). It is long, and the language caveat is restated a few times ('do not infer the work's language' recurs), but nearly every sentence carries distinct operational meaning.

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?

No output schema exists, so the description carries the burden of explaining returns, and it does so thoroughly (summary, chapters, editions, contains_works, text_role). Combined with the pipeline positioning, an agent has everything needed to call it correctly 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?

Only one parameter (book_id) and schema coverage is 100%, so the schema already documents it fully; the description adds no syntax or format detail for book_id. The rich language discussion concerns response fields and other tools' `lang` parameter, not this tool's input, so the 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?

Opens with a specific verb/role ('READ PIPELINE step 1 — DISCOVER') and explicitly enumerates what is returned (summary, chapter list, edition metadata, DOI, page counts, IIIF manifest, cover image). It positions itself precisely against siblings by naming get_book_text as 'step 2' and get_quote/get_quotes as 'step 3', so the agent can route without opening any 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?

Gives an explicit entry condition ('START HERE for any named work or author') and names alternatives with their selecting conditions (list_editions for an original-language witness, search_within_book for passages inside the book). It also states negative guidance: do not infer the work's language from `language`, and do not conclude a tradition is absent because a filter came back empty.

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 only establish the read-only/idempotent profile, and the description layers on substantial behavior: the citation_link headline, page-break continuity risk (~1 in 5 prose boundaries, hyphen splits), text_source branching including the OCR/long-s caveat for English originals, romanized being apparatus not transcription, and lang fallback with lang_note. It also warns about a concrete failure mode (quoting a fragment as a complete thought = misattribution).

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 long (~450 words) but front-loaded with the identifying clause and organized under clear headers (PAGE BREAKS, NON-LATIN SCRIPTS, ENGLISH ORIGINALS, TRANSLATED EDITIONS). Almost every line carries operative instruction; the mild cost is repetition of the text_source/lang rules already present in 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?

No output schema exists, so the description must carry the return contract — and it does: citation_link, citation.locator, continuity fields, text_source, translation/translation_note, romanized, and a concrete render template. It is complete enough for an agent to format a correct citation on the first call.

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

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

Schema coverage is 100% and the parameter descriptions are already detailed (lang especially), so the baseline is 3. The description adds workflow meaning on top: context is tied to the continuity fields and 'about to quote near a page edge', and include_image is scoped to when the user should SEE the leaf. Some of the lang/text_source content duplicates the schema, keeping this below a 5.

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

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

States a specific verb and resource ('Get the exact verbatim text of a single page plus its citation apparatus') and frames it within a named pipeline step (READ step 3 — CITE). It explicitly distinguishes itself from the sibling get_quotes ('For several pages of one book at once, use get_quotes') and from list_editions, so an agent can route without opening any 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?

Gives a hard trigger ('ALWAYS use before putting text in quotation marks') plus conditional branches: call again with context: true when continuity flags are true, use get_quotes for multi-page, call list_editions for an original-language witness. When-to-use, when-to-recurse, and alternatives are all explicit.

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

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

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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely non-structured behavior: no page-text matching, the exact return fields (title, author string + author_id + author_url, language, year, translation progress), and the caveat that an empty listing is not proof of absence. It stops short of discussing result volume or rate behavior, so it is strong but not exhaustive.

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?

Front-loaded with the verb and scope, then when-to-use, then return shape, then sibling routing, then the absence caveat — each sentence carries distinct information with no restatement of the name. The caps and arrow separators are loud but function as scan anchors rather than 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 12-parameter, all-optional read tool with no output schema, the description covers purpose, selection, return fields, and the main semantic pitfalls (metadata-only, partial year coverage handled in schema). Nothing an agent needs to invoke it 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 coverage is 75%, but the description compensates where the schema is thin — notably the undocumented sort enum, which it glosses as 'translation recency' alongside year range, and it names the filter axes (canonical author via author_id, search words, language, category). The schema itself already carries rich per-parameter guidance (work_id vs title search, has_edition vs language), so this is additive rather than duplicative.

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 ('browses/filters the catalog by metadata') and immediately bounds the scope with 'no page-text matching', which separates it from the passage/topic search siblings. It enumerates the filter dimensions and the returned fields, so an agent knows exactly what class of operation this is without opening 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?

Explicitly says when to pick it ('to see WHAT EXISTS by an author or in a tradition, or to enumerate a date range') and routes three named alternatives with their selecting conditions: search_library for relevance-ranked topics, search_translations/search_concept for passages, check_duplicate for 'do you hold X?'. It even warns that a miss here is not evidence of absence — a usage trap an agent would otherwise fall into.

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?

Annotations already establish read-only/idempotent safety, and the description adds substantial context beyond them: counts cover only book illustrations (museum-artwork collection excluded), only tags on 3+ images are listed, refresh cadence is weekly, and no returned URL is a browse page. This is exactly the kind of operational detail annotations cannot carry.

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?

Front-loads purpose, then usage, then caveats in a logical sequence. Dense but almost every clause carries decision-relevant information; the closing URL warning is slightly tangential but still operationally useful.

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?

Covers call patterns, match semantics, coverage limits, staleness, and the failure fallback. With no output schema, the note that results contain counts and non-browse URLs adequately frames the return 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?

Schema coverage is 100% so baseline is 3, but the description still adds meaning: it explains the semantic effect of omitting facet (top values of all four) and gives a concrete contains example ('ouro' -> 'ouroboros'). It does not restate the limit semantics, which the schema fully covers.

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 exactly what is listed (legal values of the type/subject/figure/symbol filters of search_images) and why (exact-match tags with huge vocabularies). An agent can immediately distinguish it from sibling search_images, which it explicitly references.

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 ('Look it up here first'), how to call it in each mode (no facet = top values; facet + contains = spelling lookup), and a named fallback ('use it as free text in search_images' query instead') for the no-match case.

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?

The annotations say readOnlyHint=false and destructiveHint=false, which is a slightly unusual gap, and the description resolves it by explaining that a proposal does not change the page and is applied only after a second reader agrees. It also adds the consequences (volunteer credited, stale base_hash rejection) and the field-sequencing rule, all of which go well beyond the annotations.

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

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

Front-loaded and mostly efficient, but the final drafted_by sentence is a dense run-on listing four enum values. It earns its keep but is the least scannable part and could be split. Otherwise every sentence carries operational weight.

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

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

There is no output schema, so the description must cover intent, sequencing, edit format, and failure handling, and it does all of those for a 10-parameter tool. An agent has what it needs to decide whether and how to call this rather than a sibling.

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 70%, so the schema already carries a fair amount. The description adds real value by defining the span-edit contract: find must be copied exactly, must occur once on the page, replacements may be empty to delete, and base_hash must be page.text_version for the chosen field. It also disambiguates the drafted_by enum values, which the schema leaves as bare strings.

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?

Names a specific verb (propose a correction) and resource (page transcription or English), then immediately defines what a correction is operationally: a list of exact span edits. This distinguishes it clearly from siblings like submit_page_review, since the description explains that a proposal does not change the page until a second reader agrees.

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 scopes use to a review shift, states the order of operations (propose transcription fixes before translation fixes, as separate calls), and defines when not to act ('Do not restyle or modernise'). It also gives the failure-handling path: if the page changed since load, say so and move on.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), but the description adds substantial extra context: similarity score calibration bands, the rule that only 'translation' snippets may be quoted and never 'summary', the diversification behavior for max_per_book, and a cost warning. This is well beyond what the annotations convey.

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

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

Front-loaded with the return shape and the 'PICK THIS when' trigger before any calibration detail, and the arrow-delimited segments make it scannable. It is nonetheless dense and long, with overlapping guidance (diversity vs max_per_book vs max_per_author) that could be trimmed.

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 14-parameter semantic search with no output schema, the description covers result nature, quote-eligibility of snippets, score interpretation, cost tradeoffs and cross-tradition query strategy. An agent has everything needed to call it correctly and read the results.

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 each of the 14 parameters is already documented in the schema with examples and edge cases (language vs languages, max_per_author dropping vs diversity re-ordering). The description's parameter notes ('Set max_per_book to diversify') largely restate the schema, so the 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?

Opens with a specific verb+resource+mechanism: 'RETURNS QUOTABLE PASSAGES matched by MEANING (cosine similarity on Gemini embeddings, 768d)'. It explicitly distinguishes itself from search_translations (exact words), search_library (book-level listing) and get_book, so an agent can route without opening any 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?

States exactly when to pick this tool ('when the modern term won't literally appear in historical texts') with concrete examples, and names three alternatives with the conditions that select them. Also gives a cost-based exclusion ('reserve it for cross-corpus discovery').

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?

Beyond the readOnly/idempotent annotations, the description discloses rendering behavior on MCP Apps vs other clients, the inline-image return for the first few results, the meaning of an empty result under book_id (note field), the offset pagination contract, and the title_is_descriptive caveat with citation guidance. This is rich operational context annotations cannot convey.

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

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

Front-loaded with what the tool returns and how results are structured, and every later sentence carries usage-critical guidance. It is a single dense block and repeats some schema content, which keeps it from a 5, but there is little true 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 an 11-parameter, no-output-schema, open-ended search tool, the description covers result structure, pagination, filtering strategy, empty-result interpretation, client rendering differences, and citation rules. Nothing an agent needs in order to search and report 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 coverage is 100% and the schema already documents offset, year_from caution, and exact-match tags, so much of the description repeats it. The description still adds meaning the schema does not: the interleaved two-lane result structure, the empty-result note semantics, and why include_thumbnail_base64 should not be requested from chat. Above the baseline 3, but not fully additive over 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 opening sentence states a specific verb (Search) plus two quantified resources (200,000+ historical illustrations and 24,000+ artworks) with a breakdown of media types. It also distinguishes itself from siblings by naming list_image_facets as the companion lookup tool and clarifying that results interleave book-illustration and museum-artwork collections.

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 routing is provided: narrow with type/subject/symbol or page with offset instead of raising limit; look up exact tag strings with list_image_facets; use book_id to restrict to extracted book images. It also states the when-not condition (offsets > 0 return only the gallery lane; book_id excludes artworks).

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral detail: what fields are searched (titles, authors, subjects, secondarily translated text) and the shape of results (total_matches, returned, offset for pagination). It also warns that results are ranked rather than exhaustive holdings, which prevents a real misuse pattern.

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 most important fact — books, not passages — is front-loaded and capitalized, and the remaining sentences each carry a distinct routing rule or query tip. It is dense with arrows and parentheticals, but nothing is filler; the density is the only cost.

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 filtered search tool with no output schema and 8 parameters, the description supplies the missing return-value contract (total_matches, returned, offset) and explicit sibling routing. An agent has everything needed to call it and interpret the response 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 88%, so parameters are already well documented; the description reinforces query syntax with concrete examples ('memory palace', 'ouroboros') and explains quoting for exact phrases. It also clarifies the offset/limit relationship to total_matches in the results, which the schema alone does not connect. Sort, year range, language, and has_translation filters are left to the schema, which is acceptable at this coverage level.

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 A LIST OF BOOKS (works on a topic) — NOT passages') and immediately contrasts with the passage-level siblings. An agent can distinguish this from search_translations, search_concept, and get_book without opening any 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?

Gives explicit routing rules: use search_translations for quotable exact words, search_concept for meaning, get_book when an author/work is already named, list_books to find IDs, and check_duplicate for holdings questions. It also states the negative case ('a ranked list is not a holdings check'), leaving nothing 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavioral context beyond them: phrase_match is an absolute 0-1 score (not relative), its absence for one-word/meaning-only hits, the found_by lanes, snippet_type distinguishing verbatim translation/ocr from AI-generated summary, and pagination fields. This is genuine added value.

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

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

The text is long, but the complexity (15 params, no output schema) justifies most of it and it is front-loaded with the routing decision in caps and arrows. Some material (phrase_match, found_by, snippet_type) bleeds into return-value explanation that could be trimmed, so not a clean 5.

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, 15 parameters and a complex corpus, the description compensates by describing return fields (phrase_match, found_by, snippet_type, total_matches, returned, offset), pagination, and the cross-cultural query strategy. Nothing an agent needs to select or invoke correctly appears 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 87%, so the schema carries most parameter documentation (diversity, max_per_work, max_per_author, exclude_authors, lang, etc.), which sets the baseline at 3. The description adds real meaning for query construction, notably the cross-cultural tip to search tradition-internal vocabulary (e.g. "jing"/"bindu" rather than "semen retention") for pre-modern topics, pushing it slightly above 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?

States a specific verb+resource (returns quotable page-level passages with citation URLs) matched by keyword/term, and explicitly names itself as the pick for finding quotes/evidence across the library. It repeatedly distinguishes itself from search_concept, search_library, search_within_book and get_book, so an agent can route without opening any 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?

Gives explicit when-to-use and when-not with named alternatives: use search_concept when the modern word won't literally appear, search_library to list books, search_within_book for one known book, get_book first if the user named an author/work. It also supplies query-construction guidance and a cross-cultural search tip, leaving little 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 only say read-only/idempotent; the description adds substantive behavior beyond them — hybrid keyword plus top-~10 semantic retrieval interleaved by relevance, absolute score calibration thresholds (0.70/0.55), found_by semantics, and front-matter results ordered last. This is exactly the kind of non-obvious retrieval behavior an agent cannot get from 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?

Front-loaded with the core verb and the divergence to search_concept, and every sentence carries usable information. It is long and caps-heavy, bordering on dense, but no sentence is 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?

With no output schema, the description compensates by explaining returned fields (score with calibration bands, phrase_match, found_by, is_front_matter), ordering rules, and that results carry page numbers and snippets ready to cite. An agent can interpret results without further documentation.

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 still adds value by stressing that book_id is mandatory and that results are ordered by relevance within that book. It does not extend the lang or offset semantics beyond what the schema already documents.

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 with scope: searches inside ONE book, requires book_id, and explicitly characterizes it as primarily lexical with a narrow scoped-semantic pass. It differentiates itself from search_concept and search_library by name and function.

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?

Gives explicit positive triggers ('know the wording', 'every page of one book mentioning a term'), explicit negative trigger ('searching from a paraphrase… USE search_concept INSTEAD'), and a prerequisite path (find the book via search_library or search_concept first).

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 already declare readOnly/destructive hints, but the description adds the interaction protocol that structured fields cannot convey: the USER is the reviewer, their verdict must be requested first, and the agent must never choose the verdict. It does not describe what the tool call itself returns as a handle/session object, which keeps it short of a 5.

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?

Front-loaded with the gating condition ("OPTIONAL lane, only for...") before the workflow detail, and every clause carries operational weight. It is a dense run-on, but no sentence is discardable.

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?

No output schema exists, and the description compensates by stating what each page contains (scan, transcription, English) and the multi-turn flow through submit_page_review. It stops short of describing the immediate return payload or session handling, but nothing critical to 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 coverage is 67%, so the schema already documents pages (1-5, default 5) and language. The description still adds meaning beyond it: pages are random and drawn from different books, and language determines which pages qualify. volunteer_code remains undocumented in both places.

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 (start a blind check) and immediately defines the scope: up to five random pages from different books, each with scan, transcription and English. It also names the sibling it replaces for other users (start_review_shift), so the agent can distinguish the two without opening either 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?

Explicit when-to-use (only for a user who reads the original language and asks to judge pages themselves) and explicit when-not ("For everyone else use start_review_shift"). It also routes the follow-up call to submit_page_review with mode "blind".

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds context the annotations cannot: the exact return payload (inline scan image, transcription, English, previous-page tail, next handoff), the session-only constraint, and the resume-vs-fresh behavior via volunteer_code or new_book. It stops short of stating error/failure behavior or what happens if the conversation ends mid-shift, so not a full 5.

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?

Purpose is front-loaded in the first clause, and the remaining sentences are dense but each carries load-bearing information (return shape, handoff protocol, resume logic, session restriction). It is long for a single paragraph and blends orchestration instructions into the description, which is a mild structure cost, but there is little dead 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?

Absent an output schema, the description compensates by describing exactly what one call returns and how it chains to continue_review_shift. All four optional parameters and the zero-required-param invocation are addressed. It is nearly complete for a complex orchestration tool; only failure modes and shift termination are unaddressed.

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 baseline 3 applies, but the description adds inter-parameter semantics the schema lacks: no book means resume the last run or auto-pick a book needing checking, new_book skips the resume, and volunteer_code is only omitted on a first shift. book's accepted formats (id, slug, reader URL) are echoed from the schema, which is the only redundant sentence.

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 ('Start a volunteer REVIEW SHIFT') and immediately explains the mechanism: the user lends their Claude to check one book, page by page, against its scans. It explicitly separates itself from continue_review_shift ('next (pass to continue_review_shift)'), so an agent can distinguish it from its closest sibling without opening either 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?

Gives explicit triggers ('wants to help Source Library', 'start a shift', 'review pages', 'asks how they can contribute') and explicit exclusions ('Run shifts only while the user is in this conversation; never set one up to run on a schedule or from a script'). It also routes the follow-up work to the sibling tool, so the when-to-use / when-to-hand-off boundary is fully drawn.

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.

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

Annotations already declare write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety profile is covered. The description adds meaningful semantics beyond that: a review is an evidence record that "does not change" the page, and findings must quote exact words. It does not describe what happens on duplicate submits or failure modes, so it stops short of a 5.

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

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

A single dense paragraph that front-loads the core action before branching into mode-specific rules and verdict vocabulary. It is efficient, though the run-on mode/verdict enumeration would be easier to scan if split into labeled lines.

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 17-parameter tool with nested findings objects and no output schema, the description covers the mode-dependent branching, verdict taxonomy, and quoting requirement well. It omits error/retry behavior and duplicate-submission handling (relevant given idempotentHint=false), which keeps it just shy of complete.

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

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

Schema description coverage is 94%, so the baseline is 3, but the description adds cross-field meaning that the schema documents in isolation: the relationship between verdict, first_verdict, assistant_verdict, and verdict_before_assistant under each mode, plus the requirement that findings quote source words. This is genuine added value over per-field 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?

States a specific verb and resource ("Record the verdict on one page of a shift") and immediately differentiates the two operating modes by naming the sibling tools that produce each (start_review_shift/continue_review_shift vs start_blind_check). An agent can distinguish this from share_findings and propose_correction without opening any 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?

Explicitly ties each mode to its originating sibling tool and specifies whose verdict applies in each case ("mode 'book-run'... the verdict and findings are YOURS" vs "mode 'blind'... the verdict is the USER'S"). It also states the precondition for user_looked and where the assistant's own verdict goes when it differs.

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