Search 15K rare pre-modern texts translated to English: philosophy, religion, science, literature.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.5/5 across 15 of 15 tools scored. Lowest: 3.4/5.
The toolset includes several search tools (search_library, search_translations, search_concept, search_within_book, search_images) and quote tools (get_quote, get_quotes) that overlap in purpose. However, detailed descriptions with 'PICK THIS' guidance distinguish them clearly for careful agents, so ambiguity is low but not absent.
All tool names follow a consistent verb_noun pattern using snake_case: get_*, list_*, search_*, propose_*, share_*, submit_*. Plural forms (get_quotes) and compound nouns (book_text, with_in_book) are predictable and intuitive.
15 tools cover a comprehensive library research workflow without unnecessary bloat. Each tool serves a distinct step in the pipeline from discovery to citation, and the count is at the upper boundary of typical well-scoped sets but remains justified.
The core workflows of discovery, reading, searching, and citing are fully covered, including canonical reference resolution (get_locus) and batch quoting (get_quotes). Minor gaps include no direct page-image retrieval (though IIIF manifest is provided) and no user-specific collection management, but these are non-essential.
get_bookGet BookAREAD PIPELINE step 1 — DISCOVER. START HERE for any named work or author. Returns the book's AI-generated summary, chapter list, edition metadata, DOI, page counts, and IIIF manifest. The summary is typically a multi-paragraph orientation covering the book's argument, structure, and significance — often answering the question without further searching. Then: get_book_text to read a chapter or page range (step 2), get_quote / get_quotes to lock specific pages with full citation apparatus (step 3). search_within_book locates passages inside this book. MULTI-WORK VOLUMES: where the scans carry running heads, contains_works lists the works the volume ACTUALLY holds with their page spans, taken from the heads the printer put on each leaf. Trust it over the title — collected-works titles routinely name works the volume does not contain, and the volume holding a work often does not name it. If contains_works is absent the scans have no heads to read; status "insufficient-heads" means it was examined and could not be decided.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | Yes | The book ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral traits well beyond the readOnlyHint/idempotentHint annotations: the summary is 'typically a multi-paragraph orientation' and 'often answering the question without further searching.' It also explains the 'insufficient-heads' status and warns that titles can be misleading, adding significant contextual nuance.
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 core purpose and return items, then logically branches into pipeline steps and edge cases. Though longer than average, every sentence carries meaningful information and the structure is clear, making it appropriately sized for 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?
Despite having no output schema, the description enumerates all substantive return contents (summary, chapters, metadata, DOI, page counts, IIIF manifest) and covers the complicated multi-work volume behavior with contains_works and status values. This fully equips an agent to understand what the tool provides and its limitations.
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 single parameter book_id is described in the schema as 'The book ID,' which is sparse but 100% covered. The description does not add further semantic detail about book_id (e.g., where to find it, format), so it relies on the schema baseline without additional enrichment.
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 explicitly states this is the first step in the READ PIPELINE: 'DISCOVER. START HERE for any named work or author.' It enumerates exact return contents (summary, chapter list, edition metadata, DOI, page counts, IIIF manifest), clearly distinguishing it from siblings like get_book_text and search_within_book.
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 by naming a step-by-step pipeline: get_book first, then get_book_text or get_quote/get_quotes, and search_within_book for passages. Also explains the multi-work volume behavior and when to trust contains_works over the title, offering concrete alternative usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_book_textRead Book TextAREAD PIPELINE step 2 — READ. Read a book's text. Call get_book first (step 1) for the chapter list, then come here. Preferred: use the chapter param to read one chapter at a time (includes [Page N] markers for citation). Alternatively, use from/to for explicit page ranges (e.g. from=1 to=50). When you find passages worth quoting, hand the page numbers to get_quote / get_quotes (step 3) for verbatim text + a citation link. TRUNCATION: the response always includes truncated: true/false. When truncated=true, the truncation_note field gives the exact next from/to values to call — this means content was cut short by a page-budget limit, NOT that the book ended. An AI agent MUST NOT infer end-of-book from pages_returned alone; check truncated first. Budget limits apply to anonymous callers (~50 pages per 24h); sign in at sourcelibrary.org/auth/signin or get an API key at sourcelibrary.org/developers for higher limits.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End page number (inclusive). Recommended chunk size: 50 pages. If the response has truncated=true, use the next from/to from truncation_note. | |
| from | No | Start page number (inclusive). Use with to for explicit page ranges. | |
| part | No | Part number (1-based) for large chapters split into multiple parts | |
| format | No | json (default, structured with per-page fields) or plain (concatenated text with page markers) | |
| book_id | Yes | The book ID | |
| chapter | No | Chapter index (0-based). Preferred over from/to — returns pre-structured chapter text with embedded [Page N] markers. | |
| content | No | Which text to include: ocr (original language), translation (English), or both (default) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent behavior, but the description adds critical runtime details: always returns truncated flag, truncation_note provides next from/to, truncation is budget-based and not end-of-book, page-budget limits for anonymous callers, and authentication paths. This exceeds the annotations and prevents a serious misinterpretation.
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 longer than average, but every sentence adds necessary context: pipeline step, usage modes, truncation warning, budget/auth note. It is front-loaded with the core purpose and structured with bolded labels. While not as terse as the TDQS 4.3 example, it is appropriately sized for 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 7 parameters and no output schema, the description compensates well by explaining the truncation contract, the meaning of truncation_note, the presence of [Page N] markers, and budget limitations. Combined with the schema's format/content enums, an agent has enough context to invoke the tool correctly, interpret results, and handle pagination.
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?
Input schema coverage is 100%, so baseline is 3. The description adds value by explaining the preferred chapter parameter (with [Page N] markers) versus explicit from/to ranges, the truncation_note for next call, and the chunk-size recommendation (50 pages). It doesn't explain every parameter, but the schema already does; the extra workflow guidance earns a 4.
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 'READ PIPELINE step 2 — READ. Read a book's text.' and positions the tool within a multi-step workflow (get_book → this → get_quote/get_quotes). It specifies both the action and the resource, and distinguishes it from siblings by naming the exact pipeline steps and when to move to other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit instructions: 'Call get_book first (step 1) for the chapter list, then come here.' It also provides a preferred method (chapter param) and an alternative (from/to), plus guidance to hand page numbers to get_quote/get_quotes for verbatim text. This fully answers when and how to use the tool, including alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_locusFind a Canonical Reference (Bekker / Stephanus)ATurn a CANONICAL CITATION into the actual leaves that carry it. Aristotle is cited by Bekker number (1094a8, 1447a) and Plato by Stephanus number (Rep. 328b) — the references scholarship has used for centuries, which survive re-typesetting and are shareable in a way a scan page never is. USE THIS FIRST whenever a passage arrives as a canonical reference rather than a page: do not try to derive the page yourself from a book's pagination, which is what produced a wrong guess before this tool existed. Bekker numbers are unique across the whole Aristotelian corpus, so the number alone is enough and it also tells you WHICH WORK you are citing. Stephanus numbers restart in each of the three 1578 volumes, so pass work ("Republic", "Timaeus") — without it the response lists the candidate dialogues instead of choosing one. Returns every witness the library holds: the Greek reference edition and, where we have one, an English translation of the same lines, each with its scan page, a reader URL and a quote_api link — so you can compare the original against a translation at one reference. Then call get_quote with the returned book_id + page for the verbatim text and a citable shortlink. LIMITS, stated plainly: a witness is only returned where the reference is PRINTED on that leaf (or, in the two root editions, where a verified constant offset brackets it) — nothing is interpolated, so an empty result means this library holds no anchored leaf there, NOT that the citation is wrong; editions_searched shows what was consulted and the range each covers. Line numbers (the "8" of 1094a8) are not resolved — you get the right leaf and read the line off it. Two works can share a page where one ends and the next begins (Bekker 184 and 1447 are both such joins), and each leaf is filed by the running head printed on it, so a reference at the very start of a work may come back under its predecessor — always read other_works_at_this_reference before concluding a passage is absent. A bare number that exists in both systems returns Aristotle and Plato leaves together; check the system field on each.
| Name | Required | Description | Default |
|---|---|---|---|
| work | No | The work or dialogue, when the reference needs it (Plato always does): "Republic", "Timaeus", "Laws", "Nicomachean Ethics", "Poetics". Greek or Latin titles as printed in the editions also resolve. | |
| system | No | Optional: "bekker" or "stephanus". Inferred from the work when omitted; do not guess it from the number, since the two ranges overlap. | |
| reference | Yes | The canonical reference: "1094a8", "1094a", "1447", "328b". A leading system name is accepted ("Bekker 1094a"), as is a work name ("Rep. 328b"). |
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.
get_quoteGet QuoteAREAD PIPELINE step 3 — CITE. Get the exact verbatim text of a single page plus its citation apparatus. ALWAYS use before putting text in quotation marks. The response headline is citation_link (the stable sourcelibrary.org/q/… shortlink) — present it to the user alongside the quote. Render as:
[exact translation text, verbatim] — [Author], p. [N]. [citation_link] PAGE BREAKS: this corpus is paginated from physical leaves, and nearly one prose page-boundary in five has a sentence running across it — sometimes a word split by a hyphen ("…our move-" / "movements…"). A page that opens or breaks off mid-sentence still reads as complete prose and still carries a perfectly valid citation, so check the continuity field on every response BEFORE quoting: if continues_on_next or continues_from_previous is true, call again with context: true and quote the whole sentence. Quoting a fragment as though it were the author's complete thought is a misattribution even when the page number is right. For several pages of one book at once, use get_quotes.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Page number | |
| book_id | Yes | The book ID | |
| context | No | Also return the full text of the previous and next pages, so a sentence spanning the page break can be read whole. Set this when continuity.continues_from_previous or continues_on_next came back true on an earlier call, or whenever you are about to quote near a page edge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains pagination and page-break issues ('nearly one prose page-boundary in five has a sentence running across it'), warns of misattribution risk when quoting fragments, and specifies the response's headline citation_link plus a rendering template. This adds context beyond the readOnly/idempotent 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 long, every sentence serves a purpose: the rendering example, the page-break warning, and the sibling-tool pointer. Front-loaded with purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive: covers return value (citation_link), rendering format, page-continuity edge cases, and explicit 'use get_quotes' alternative. No output schema exists, but description provides necessary contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3, but description elevates by explaining the `context` parameter's purpose and when to set it (when continuity flags are true or near page edge).
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?
Identifies tool as 'READ PIPELINE step 3 — CITE' and specifies 'exact verbatim text of a single page plus its citation apparatus.' Distinguishes from sibling get_quotes by noting multi-page use.
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 a hard rule: 'ALWAYS use before putting text in quotation marks.' Directs users to call with context:true when continuity fields are true and names get_quotes as alternative for multiple pages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_quotesGet Quotes (batch)AREAD PIPELINE step 3 — CITE, in batch. Get verbatim text + citation_link for SEVERAL pages of a single book in one round-trip, to assemble a multi-passage dossier. Specify either pages (an explicit array, e.g. [12, 40, 41]) or an inclusive from/to range. Max 25 pages per call. Each entry carries its own citation_link to present alongside the quote.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End page (inclusive) of a range. Use with from. | |
| from | No | Start page (inclusive) of a range. Use with to. | |
| pages | No | Explicit list of page numbers (e.g. [12, 40, 41]). Use this OR from/to. | |
| book_id | Yes | The book ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent, so the description adds beyond that: it reveals the max 25-page limit, that each entry carries its own citation_link, and that it returns verbatim text. This enriches the behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with a pipeline context, and every sentence adds value (purpose, modes, limit, output format). No wasted verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only batch retrieval tool with no output schema, the description adequately explains the return content (verbatim text + citation_link) and operational constraints (single book, max 25 pages). It could mention error handling for out-of-range pages, but that is not essential given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds semantic relationships: explains that pages is an alternative to the from/to range, gives a concrete example, and states the max page count. This goes beyond the schema's individual property 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 clearly states a specific verb+resource+scope: 'Get verbatim text + citation_link for SEVERAL pages of a single book in one round-trip.' It distinguishes from the sibling get_quote by emphasizing batch retrieval and names the output fields.
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 indicates when to use the tool ('in batch', 'one round-trip') and explains the two input modes (explicit pages array or from/to range). It implicitly differentiates from the singular get_quote, though it does not explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_booksList BooksABROWSES/FILTERS THE CATALOG by metadata (author/title fragment, language, category, translation recency) — no content/topic matching. PICK THIS to see WHAT EXISTS by an author or in a tradition. Returns books with title, author, language, year, and translation progress. → For a relevance-ranked topic search use search_library; for passages on a theme use search_translations (exact words) or search_concept (by meaning).
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| limit | No | Max results (default 100, max 200) | |
| search | No | Filter by title or author | |
| category | No | ||
| language | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the key limitation 'no content/topic matching' and specifies the response fields (title, author, language, year, translation progress). This is additional 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 tight, with a leading capitalized action, then a clear directive, return information, and alternatives in two sentences. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, the filtering dimensions, return fields, and when to use alternatives. Even without an output schema, the return format is summarized, making the tool fully understandable.
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 adds meaning to parameters by enumerating metadata facets (author/title fragment, language, category, translation recency) which map to search, language, category, and sort. With schema coverage only 40%, this compensates meaningfully, though it doesn't individually describe each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('BROWSES/FILTERS THE CATALOG') plus the metadata dimensions, clearly distinguishing it from sibling search tools. It also states the return fields, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'PICK THIS to see WHAT EXISTS by an author or in a tradition' and directly names alternatives (search_library, search_translations, search_concept) with their different purposes. This is model guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_editionsList Editions of a WorkAEvery edition of one work that the library holds — the other witnesses to the same text, across languages and centuries. Give it a book_id (easiest: the id of any edition you already found) or a work_id. USE THIS when a quotation needs checking against more than one witness, when you want the original-language text behind a translation, or when comparing how a passage reads across editions — differences between witnesses are often the finding. Returns language, date, page count and translation coverage per edition, so you can pick the right one to read. Note: for multi-volume collected works the identifier names the SET rather than a single text, and the response says so explicitly when that applies.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | No | Any edition you already have. Its work is looked up and the siblings returned. | |
| work_id | No | A work identifier, if you already have one (from get_book). |
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.
propose_collectionPropose a CollectionAInspectPropose a themed collection of books to the Source Library team — a title, a rationale (why these books belong together and what thread connects them), and an ordered list of book ids. Get book ids from search_library / list_books / get_book. Like submit_feedback and share_findings, this goes to the team for REVIEW — it does NOT create a public collection instantly; a curator reviews and approves it. Use this when the user has identified a coherent set of books worth grouping and wants to contribute that curation back.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| No | |||
| title | Yes | Title of the proposed collection (2-200 chars) | |
| book_ids | Yes | Ordered list of book ids to include (1-200). Get ids from search_library / list_books / get_book. | |
| rationale | Yes | Why these books belong together and what connects them (max 5000 chars) | |
| suggested_slug | No | Optional URL slug suggestion, e.g. "renaissance-astronomy" |
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.
search_conceptSearch by ConceptARETURNS QUOTABLE PASSAGES matched by MEANING (cosine similarity on Gemini embeddings, 768d) — paraphrases and adjacent phrasings match even with zero keyword overlap. PICK THIS when the modern term won't literally appear in historical texts — e.g. "distributed cognition" maps to passages about active intellect, art of memory, wax tablet metaphors; "social contract" maps to pre-Hobbesian discussions of consent and authority. → For exact words/distinctive terms use search_translations (cheaper, more precise); to list which BOOKS cover a topic use search_library; if the user named an author/work, get_book first (semantic search is expensive — reserve it for cross-corpus discovery). Similarity calibration: 0.70+ is a strong match, 0.55–0.70 is worth reading but verify, below 0.55 is mostly conceptual drift. Set max_per_book to diversify results across many books rather than cluster on one source. Each passage carries a snippet_type — quote only "translation" snippets, never "summary". Cross-cultural tip: for pre-modern or non-Western topics, also try source-tradition vocabulary — e.g. for seminal economy try "jing preservation" or "bindu yoga" or "istimnāʾ"; for masturbation try "mollities" (Latin) or "hastamaithuna" (Sanskrit) or "shouyin" (Chinese). The corpus is indexed via period translations that use tradition-internal terminology, so adjacent/euphemistic terms often surface material that modern English keywords miss.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max passages (default 15, max 50) | |
| query | Yes | A concept or natural-language description — full sentences are fine (e.g. "tools that extend the mind beyond the body"). Unlike search_translations, this does NOT require words that appear in the corpus. | |
| year_to | No | Restrict to books published in or before this year. | |
| language | No | Filter by a single original language | |
| languages | No | Filter to any of these languages, e.g. ["Sanskrit", "Arabic", "Chinese"]. Use instead of language when targeting multiple traditions. | |
| year_from | No | Restrict to books published in or after this year (filters out modern editions and translations). | |
| max_per_book | No | Cap on passages from any single book. Useful when one book dominates the conceptual neighborhood; set to 1–2 for diverse author/work coverage. | |
| exclude_languages | No | Exclude these languages, e.g. ["Latin", "French", "German", "English"] to surface non-Western sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true, idempotentHint=true), the description discloses similarity calibration thresholds (0.70+ strong, 0.55-0.70 verify, below 0.55 drift), the snippet_type rule ('quote only "translation" snippets, never "summary"'), and the cost/expense of semantic search. 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 front-loaded with the core function and rich with examples and actionable guidance. It is long but every sentence adds value for a complex semantic search tool; a compact summary could be added but current structure is organized with arrows and clear topic shifts.
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 carries the burden of explaining return values and behavior. It covers the return type (quotable passages), snippet_type handling, similarity calibration, max_per_book diversity, and cross-tradition vocabulary tips. This is exceptionally complete for the tool's complexity.
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. The description adds meaningful context beyond schema: query is explained as natural-language/description not requiring literal words, max_per_book guidance (set 1-2 for diverse coverage), and use cases for language filters (exclude_languages to surface non-Western sources). This enriches 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?
Description states 'RETURNS QUOTABLE PASSAGES matched by MEANING (cosine similarity on Gemini embeddings, 768d)' — a specific verb+resource+method. It also explicitly differentiates from search_translations, search_library, and get_book, making sibling distinction clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description gives explicit when-to-use guidance: 'PICK THIS when the modern term won't literally appear in historical texts' and names alternatives: 'For exact words/distinctive terms use search_translations (cheaper, more precise); to list which BOOKS cover a topic use search_library; if the user named an author/work, get_book first'. Also warns that semantic search is expensive and should be reserved 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.
search_imagesSearch ImagesASearch 110,000+ historical illustrations, emblems, engravings, diagrams, AND 23,000+ artworks (paintings, prints, sculptures). Filter by type, subject, figure, symbol, year.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Image type (woodcut, engraving, emblem, diagram) | |
| limit | No | Max results (default 20, max 50) | |
| query | No | Text search (e.g., "ouroboros", "tree of life") | |
| figure | No | ||
| symbol | No | ||
| book_id | No | ||
| subject | No | ||
| year_to | No | ||
| year_from | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context about the scope (110,000+ illustrations and 23,000+ artworks) and available filters. It does not mention result format, pagination, or behavior with empty queries, but the safety profile is covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the key resource types and then lists filter dimensions. Every word contributes useful information, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 9 optional parameters and no output schema, the description provides a reasonable overview but omits important contextual details such as how results are returned, ordering, or the effect of omitting all filters. The annotations cover safety, but the description does not fully define search behavior for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description must compensate. It mentions type, subject, figure, symbol, and year—mapping to most parameters—but does not explain book_id or the exact semantics of year_from/year_to ranges. This adds some meaning beyond the schema but leaves several parameters under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as searching historical images, with specific resource counts (110,000+ illustrations and 23,000+ artworks). It distinguishes this from sibling tools like search_library or search_query by emphasizing visual content and lists concrete filter dimensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for image search, covering a broad corpus of visual materials. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the context is clear enough for an agent to infer it should be used for image-related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_librarySearch LibraryARETURNS A LIST OF BOOKS (works on a topic) — NOT passages. PICK THIS to discover which works exist on a subject. → For quotable text 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) — the AI summary + chapter outline is usually the right first answer. Searches titles, authors, subjects, and (as a secondary signal) translated text. Query tips: single distinctive words or short phrases work best ("memory palace", "ouroboros"); quoted phrases match exactly. Each result includes total_matches (full count) + returned (this page) + offset for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| limit | No | Max results per page (default 10, max 100) | |
| query | Yes | Search query — prefer single distinctive concepts ("alchemy", "tree of life") over long natural-language phrases. Wrap in "double quotes" for exact phrase. | |
| offset | No | Pagination offset (use with limit to page through total_matches; default 0) | |
| year_to | No | Publication year range end | |
| language | No | Filter by original language (e.g., Latin, German, Greek) | |
| year_from | No | Publication year range start | |
| has_translation | No | Only return books with translations |
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.
search_translationsSearch TranslationsARETURNS QUOTABLE PASSAGES (page-level snippets + citation URLs), matched by KEYWORD/term. PICK THIS to find a quote or textual evidence on a topic across the whole library. → If the modern word won't literally appear in historical texts, use search_concept (matches by meaning); to list which BOOKS cover a topic use search_library; to dig inside one known book use search_within_book; if the user named an author/work, get_book first (its AI summary is usually the right first read). Query tips: single distinctive terms ("memory palace", "wax tablet") work best; multi-word natural-English queries ("unity of the intellect") may return fewer results because matching is term-based, not phrase-based. Each snippet has a snippet_type — "translation"/"ocr" means it is a verbatim extract from the source text; "summary" means it is AI-generated description (do not quote those as the author's words). Response includes total_matches, returned, and offset for pagination. Cross-cultural tip: for pre-modern or non-Western topics, search source-tradition vocabulary rather than modern English terms — e.g. for seminal economy search "jing" or "bindu" or "istimnāʾ", not "semen retention"; for female homoeroticism search "tribade" or "sahq", not "lesbian". The corpus is indexed via period translations that use tradition-internal terminology.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results per page (default 20, max 50) | |
| query | Yes | Search term — prefer single distinctive concepts ("harmony of the spheres", "active intellect") over long natural-language phrases. Multi-word queries match all terms (not phrase); wrap in "double quotes" for exact phrase. | |
| offset | No | Pagination offset (use with limit to page through total_matches; default 0) | |
| book_id | No | Search within a specific book | |
| year_to | No | ||
| language | No | Filter by a single original language | |
| languages | No | Filter to any of these languages, e.g. ["Sanskrit", "Arabic", "Chinese"]. Use instead of language when targeting multiple traditions. | |
| year_from | No | ||
| exclude_languages | No | Exclude these languages, e.g. ["Latin", "French", "German", "English"] to surface non-Western sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations, disclosing that matching is term-based not phrase-based, explaining snippet types ('translation'/'ocr' verbatim vs 'summary' AI-generated), warning against quoting summaries as author's words, and detailing pagination fields. It also provides cross-cultural vocabulary tips, adding rich behavioral context without contradicting the readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long (over 200 words) but every sentence earns its place given the tool's complexity (9 parameters, multiple sibling tools). It is front-loaded with the core purpose and 'PICK THIS' directive, followed by usage alternatives, query tips, snippet types, pagination, and cross-cultural examples. Well-structured and appropriately sized for the context.
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 guidelines, query tips, snippet type semantics, pagination behavior, and cross-cultural considerations. Combined with the detailed input schema, the description provides a complete picture for an agent to invoke the tool correctly. No output schema exists, but the description mentions response fields (total_matches, returned, offset).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 78% (high), so the schema already documents most parameters. The description adds value by explaining query behavior (single distinctive terms work best, multi-word matching is term-based) and mentioning snippet_type and pagination beyond the schema. It does not explicitly walk through each parameter but reinforces and augments 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 clearly states the tool returns quotable passages with page-level snippets and citation URLs matched by keyword/term. It distinguishes itself from sibling tools by explicitly naming search_concept, search_library, and search_within_book, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'PICK THIS to find a quote or textual evidence' and then gives concrete alternatives for different scenarios (search_concept for conceptual matching, search_library for listing books, search_within_book for a known book, get_book for author/work). This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_within_bookSearch Within BookASEARCHES INSIDE ONE BOOK (requires book_id). PRIMARILY KEYWORD: it runs a lexical search over the book's pages plus a narrow scoped-semantic pass (top ~10), interleaved by relevance. PICK THIS when you know the wording you are looking for, or want every page of one book mentioning a term. → IF YOU ARE SEARCHING FROM A PARAPHRASE, a half-remembered line, or a modern restatement, USE search_concept INSTEAD — it is the meaning-matching tool and it searches the whole corpus, including translations whose vocabulary differs completely from yours (Thomas Taylor writes "energies" for energeia and "felicity" for eudaimonia, so a sensible modern paraphrase can miss his pages entirely while matching semantically). → To find the book first, use search_library or search_concept, then pass its book_id here. Each result carries score (0-1, normalised within this book) and found_by ("keyword", "semantic", or "both" — both is the strongest signal). Results flagged is_front_matter are the translator's or publisher's words rather than the author's, and are ordered last. Returns OCR and translation snippets with page numbers, ready to cite.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| book_id | Yes | The book ID to search within |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses the dual-pass search mechanism (lexical plus scoped-semantic top ~10), the interleaving by relevance, result fields such as score and found_by, and the special handling of front matter. It also describes the output format (OCR and translation snippets with page numbers), providing deep behavioral transparency.
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?
Although longer than average, the description is front-loaded with the core purpose and uses clear visual cues (capitalized keywords, arrows, bullet-like points) to structure guidance. Every section adds value, including the well-explained search_concept alternative with a concrete example, and no sentence is wasted.
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 full responsibility for explaining return values, which it does thoroughly: score normalization, found_by indicators, front matter flag and ordering, and the nature of returned snippets. It covers search behavior, prerequisites, and alternatives, making it complete for an AI to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both query and book_id, achieving 100% schema description coverage. The description reinforces that book_id is required and implies the query is a keyword, but it does not add detailed parameter constraints, formats, or examples beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'SEARCHES INSIDE ONE BOOK (requires book_id)', a specific verb+resource+scope statement that immediately distinguishes it from sibling tools like search_concept and search_library. It further clarifies the primary keyword nature and the semantic pass, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('PICK THIS when you know the wording you are looking for, or want every page of one book mentioning a term') and when to use an alternative ('IF YOU ARE SEARCHING FROM A PARAPHRASE... USE search_concept INSTEAD'). It also provides a clear workflow suggestion to find the book first via search_library or search_concept and then pass its book_id here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_feedbackSubmit FeedbackBInspectSubmit feedback, bug reports, or feature requests to the Source Library team.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| No | |||
| message | Yes | Your feedback (2-20000 chars). Long structured reports are welcome — the limit was raised from 5,000 because agent reports were pressing against it and being split across submissions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is a write operation (readOnlyHint=false) and non-destructive. The description adds no additional behavioral context, such as rate limits, confirmation behavior, or whether submissions are anonymous. It simply restates the action without disclosing any 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 a single, concise sentence that fully captures the tool's purpose. It is front-loaded with the action and resource, and every word earns its place 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?
The tool is simple, but the description leaves gaps: no parameter explanations for name/email, no usage guidance relative to siblings, and no behavioral details. Given the low schema coverage and presence of sibling tools, the description is adequate for basic understanding but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), with only 'message' having a description. The tool description does not compensate by explaining the purpose of 'name' and 'email' parameters. It adds no parameter semantics beyond what the schema already provides, leaving the agent to guess their 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?
The description clearly states the verb 'Submit' and the resource: 'feedback, bug reports, or feature requests' to the 'Source Library team'. This is specific and distinguishes it from sibling tools like 'propose_collection' and 'share_findings', which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when submitting feedback, bug reports, or feature requests) but does not explicitly mention alternatives or exclusions. There is no guidance on when not to use it or how it relates to sibling tools like 'share_findings' or 'propose_collection'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!