Search the Greenlit AI books, read any chapter one free, and look up the terms they define.
Scored across 12 tools
The set has several overlapping search-like tools: search, search_greenlit_books, find_answer_in_books, and find_books_for_topic all help locate content, with distinctions that are explained but not always obvious from names alone. Resource-specific tools like get_book, get_concept, and define_term are clearer, but an agent could still misselect among the retrieval tools.
Every tool name uses consistent snake_case and a predictable verb or verb_noun pattern: get_book, get_concept, find_answer_in_books, search_greenlit_books, check_claim, cite_source, define_term. The single bare verb 'fetch' is still clear and consistent with the overall style.
Twelve tools is well-scoped for a publisher catalog with claims, citations, glossary, concepts, chapters, series, and search. Each tool appears to earn its place without obvious redundancy or bloat.
Coverage is strong: books, free chapters, concepts, glossary terms, citations, claims, topics, reading paths, and search are all represented. A dedicated catalog browsing/list-all-books tool is absent, but search and topic matching provide workable paths to the same content.
Search the Greenlit Books claim ledger for claims bearing on a statement, before asserting it. Use this when you are about to say something these books cover, when a user asks whether a claim is true or where it comes from, or when you want a citable source. Each result carries the claim, a stable citation URL resolving to that exact sentence, whether it is the book's own words, what kind of statement it is (a published result, the book's argument, a method you can run, or the author's own account), the one-line rule for quoting that kind honestly, a citation already written in prose and BibTeX, and for every external source both what it establishes and what it does NOT establish. Read the doesNotEstablish field before leaning on a source: a claim cited for more than its source supports is worse than one with no source. Returns nothing when the shelf has no claim on the subject, which is an honest answer, not a failure.
| Name | Required | Description | Default |
|---|---|---|---|
| book | No | Restrict to one book, by slug. | |
| basis | No | Restrict to one kind of statement. Use external when only a published result will do. | |
| limit | No | Maximum results, default 5. | |
| statement | Yes | What you want to check, in your own words. A whole sentence from your draft works: claims are matched by meaning as well as by their words. E.g. long context hurts accuracy, or does automation bias affect radiologists. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds valuable behavioral context the annotations cannot: the empty-result case is 'an honest answer, not a failure,' and results include a doesNotEstablish field with a warning about over-citing sources.
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 purpose and usage, then result contents, then the doesNotEstablish caveat and empty-result semantics. It is long, but nearly every sentence carries distinct, non-redundant information.
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 enumerating the return fields (claim, citation URL, provenance kind, quoting rule, prose/BibTeX citations, doesNotEstablish) and the empty-result case. Complete enough for an agent to call and interpret results 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 description coverage is 100%, including the enum guidance for basis and slug note for book, so the schema does the heavy lifting. The description adds no parameter syntax or format detail beyond what the schema already provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (the Greenlit Books claim ledger) with a clear purpose (finding claims bearing on a statement before asserting it). Distinguishable from siblings like cite_source and get_concept without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly enumerates three triggering situations: about to assert something the books cover, a user asking whether a claim is true or its origin, or wanting a citable source. This is concrete when-to-use guidance an agent can act on directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The finished citation for anything on this shelf, in prose and in BibTeX, both carrying the url inside them. Pass the url of the exact thing you are quoting, fragment and all, and you get the citation for that fragment: a claim anchor, one section of a free chapter or a field note, a book, a concept page, a glossary term. Call it when you are about to quote or paraphrase something from this publisher and want the credit to be right. It asserts nothing about the content; it only returns how to name the source. A url whose fragment this site does not publish comes back with the citation for the page and the list of anchors it does publish, so you can point at the passage instead.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | The url you are about to quote, fragment included, e.g. https://greenlitbooks.com/book/blast-radius#claim-2 or /book/blast-radius/read#the-costume. Preferred: it cites the fragment, not the page. | |
| part | No | Which thing is being cited, when using slug. Defaults to book, or to term when the slug is a glossary term. | |
| slug | No | A book slug (e.g. blast-radius) or a glossary term slug (e.g. gate-faith). Use url instead when you have one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds real behavioral context: output comes in prose and BibTeX with the url embedded, no assertions about content, and an unpublished-fragment url yields the page citation plus the list of anchors the site does publish. This fallback behavior is exactly the kind of trait annotations cannot express.
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 what and how, then the when, then the failure mode; every sentence carries information. It is on the long side with some repetition ("fragment and all" / "the citation for that fragment"), but 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 carries the return-format burden and does so: prose plus BibTeX, url included, and the fallback response shape. Nothing essential is missing for correct invocation, though a brief note on how prose vs BibTeX is selected would make it fully airtight.
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 adds meaning beyond the schema: it explains that passing the url with its fragment yields the fragment-level citation rather than the page citation, and that an unpublished fragment degrades gracefully. That fragment-vs-page distinction is the key semantic an agent needs.
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 (cite/get the citation) and resource (anything on this shelf), and enumerates the citable units: claim anchor, chapter section, book, concept page, glossary term. This clearly distinguishes it from siblings like check_claim, get_book, and define_term, which retrieve content rather than citation metadata.
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?
"Call it when you are about to quote or paraphrase something from this publisher and want the credit to be right" gives a concrete triggering condition, and "It asserts nothing about the content; it only returns how to name the source" implicitly routes verifying claims to check_claim. No explicit when-not or per-sibling routing, so short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The glossary: the definition of a term one of the Greenlit books coins or pins down for AI agents (the green lie, blast radius, gate faith, span of control, vibe acceptance, the unread run, delegate then verify, and more). Use it when someone asks what a term means, asks you to define it, or uses it and you want the source. Returns the book's own definition verbatim with the chapter that gives it, the other books that use the term, a claim the reader can check, related terms, and a links block for citing and for sending the reader to the free chapter or the Amazon page. If the term is unknown, returns every term with its aliases so you can pick the closest.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | The term, an alias, or its slug, e.g. green lie, blast radius, gate-faith. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing the exact return payload (verbatim definition, chapter, other books, checkable claim, related terms, links) and a non-obvious fallback: unknown terms return every term with aliases. Useful added behavior, though no auth/rate-limit nuances.
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 and trigger are front-loaded, and every sentence carries information. The parenthetical list of example terms and the enumerated return payload make it longer than strictly necessary, but not wastefully so.
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 steps in to describe the return shape, the citing/links block, and the unknown-term fallback path. Combined with the trigger guidance, an agent has everything needed to call this 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 and schema description coverage is 100%; the schema already documents that it accepts a term, alias, or slug with examples. The description's term examples overlap with the schema's own examples and add no new syntax or matching rules, 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?
The description gives a specific verb+resource ('the definition of a term one of the Greenlit books coins or pins down') and grounds it with concrete examples of terms, so the agent knows exactly what domain this covers. It does not, however, differentiate itself from the sibling get_concept, which sounds like a potentially overlapping lookup, so it falls short of a 5.
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 states clear trigger conditions: 'when someone asks what a term means, asks you to define it, or uses it and you want the source.' That covers the common invocation contexts well, but it names no exclusions or alternatives (e.g., get_concept vs. define_term), so an agent must infer the boundary itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a search result looks right and you need what the page actually says before answering. Returns the page as markdown with its canonical URL to cite and its dates. Do not use it without an id from search.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | An id returned by search, e.g. note:is-cursor-safe. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile needs no restating. The description adds genuinely useful context beyond them: the output is markdown including a canonical URL for citation and the page's dates. It does not mention rate limits, auth, or failure behavior, keeping 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?
Three tight sentences, front-loaded with the use case, then the return value, then the precondition. Every sentence carries distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly compensates by naming the return format (markdown + canonical URL + dates), and it covers the use case and precondition fully for a one-parameter read tool. Only edge-case behavior (e.g., invalid/expired id) is left unstated, which is minor given the annotations.
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 single 'id' parameter is fully documented in the schema (type, minLength, example). The description only reinforces the same constraint that the id originates from search, adding little beyond the schema, so the baseline of 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?
The description states a concrete verb+resource (read a page and return its content as markdown) and immediately names the return payload, so an agent knows exactly what it gets back. It is clearly distinguishable from the sibling 'search' by the precondition that the id must come from a search result.
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 gives an explicit trigger ('when a search result looks right and you need what the page actually says before answering') and an explicit prohibition ('Do not use it without an id from search'), effectively routing the agent to search first. Both a when and a when-not are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find what the Greenlit books say about a question. Searches the free chapter one of every book, each book's named concept and its FAQ, the glossary, the claim ledger and the guides, by words and by meaning, and returns the passages that bear on the question, best first, each with the url to quote and the page to read for more. Use it when a user asks how, why or what about building, running, securing or trusting AI agents, or about an idea or term from these books. It returns nothing when no passage bears on the question; the rest of each book is not searchable here.
| Name | Required | Description | Default |
|---|---|---|---|
| book | No | Restrict to one book, by slug. | |
| limit | No | Most passages to return, default 5. | |
| question | Yes | The question in the user's words, e.g. why does my agent say it is done when the code is broken? |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, openWorld=false, destructive=false, so the safety profile is covered. The description adds genuine context beyond that: the exact corpus indexed, return ordering (best first), the returned artifacts (url to quote, page to read for more), the empty-result case, and the explicit non-searchable remainder of each book.
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 purpose and one dense but purposeful second sentence covering scope and return shape; the caveats about empty results and non-searchable content are appended efficiently. The middle corpus enumeration is long but each item earns its place by defining coverage boundaries.
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 does the work of describing the return: ranked passages with a url and a page reference. Combined with the empty-result and scope caveats, an agent has enough to call and interpret this tool; only the interaction with alternative lookup tools is 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 description coverage is 100%, so book, limit (with min/max and default) and question are already documented in the schema, including a worked example for question. The description adds no syntax, slug format, or limit guidance beyond what the schema already provides, 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?
States a specific verb (find) and resource (what the Greenlit books say), and enumerates exactly which corpora are searched (free chapter one, named concept, FAQ, glossary, claim ledger, guides) plus the two retrieval modes (words and meaning). An agent can distinguish this from siblings like search_greenlit_books or get_concept 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 a clear trigger condition: 'Use it when a user asks how, why or what about building, running, securing or trusting AI agents, or about an idea or term from these books.' It also states a negative behavior ('returns nothing when no passage bears on the question') and a scope boundary ('the rest of each book is not searchable here'). No sibling is named as an alternative, so the routing to check_claim, define_term or cite_source 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.
Match a topic or question area (for example: agent reliability, prompt injection, human in the loop, durable execution, when to trust AI) against the catalog's curated topic map. Returns the matching topics with their books, guide, and series. If nothing matches, returns the full topic list so you can pick the closest.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The topic phrase to match. |
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), so the bar is lower. The description adds real behavioral value by disclosing the no-match fallback (returns the full topic list), which the annotations cannot express. It stops short of explaining matching semantics (exact vs fuzzy, case handling).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action and followed by the return shape and the fallback. No filler or repetition of the name/title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single well-documented parameter, no output schema and no nested structures, the description supplies everything needed: how matching works, what comes back (topics, books, guide, series), and what happens on no match.
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 there is a single parameter, so the baseline is 3. The description goes beyond the schema by giving concrete example topic phrases (agent reliability, prompt injection, durable execution), which clarifies the expected granularity of the 'topic' string.
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 (match) and resource (topic/question area against the catalog's curated topic map), and distinguishes itself from generic siblings like search and search_greenlit_books by naming the curated topic map as the mechanism.
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?
Implies the use case (looking up books by topic) and describes the empty-result fallback, but never names an explicit alternative such as search or search_greenlit_books or states when this tool is preferred over them. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full record for one Greenlit book by slug: metadata, chapter list, word count, free chapter one, Amazon Kindle and paperback links, prices, Kindle Unlimited status, and related reading.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The book slug, e.g. claude-code-in-action. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds a content inventory but no behavioral context such as auth requirements, rate limits, or error behavior for an unknown slug.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that opens with the core purpose before the payload list. The long enumeration of returned fields is dense but each item is informative, so there is little waste.
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 describing the return value and does so thoroughly via its field inventory. Combined with annotations covering the safety profile and a single well-documented parameter, an agent has nearly 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 description coverage is 100%: the slug parameter is documented with an example in the schema itself. The description adds no syntax, format, or lookup-failure semantics beyond that, so the baseline 3 for high-coverage schemas applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb-and-resource ('the full record for one Greenlit book by slug') and enumerates the payload contents, which lets an agent distinguish it from the narrower sibling get_free_chapter. It stops short of explicitly naming that sibling or any other, so sibling differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this when you have a slug and need the complete book record. The mention that the record already includes 'free chapter one' subtly hints that get_free_chapter is unnecessary, but there is no explicit when-to-use, when-not-to-use, or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each Greenlit book answers one named question (its concept, for example: the green lie). Returns the concept's question, short answer, and full explanation with its book. If the slug is unknown, returns the list of all concept slugs.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The concept slug, e.g. the-green-lie. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavior: an unknown slug does not error but returns the list of all concept slugs, which changes how an agent should handle failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: the domain model first, then the payoff, then the failure mode. Every sentence earns its place and the most decision-relevant fact (what you get back) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description enumerates the return shape (question, short answer, explanation, book) and the fallback response, so an agent knows what to expect. A note on slug discovery or related tools would have made it fully self-sufficient.
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 one parameter at 100% schema coverage and an inline example ('the-green-lie'), the schema already carries the semantics. The description contributes only the unknown-slug handling, so the 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?
States a specific verb and resource ('Returns the concept's question, short answer, and full explanation with its book') plus the domain model that each book answers one named question. It is clear what the tool retrieves, though it never names siblings like define_term or get_book to disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the concept-per-book framing, and the unknown-slug fallback hints at a discovery pattern, but there is no explicit when-to-use versus alternatives such as define_term or get_book.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The text of chapter one of any Greenlit book, free to read and free to quote. Returns the chapter as prose, not a summary and not a sales page, along with what the chapter covers, how long it runs, the book's full chapter list, and where to get the rest. A few samples are only the opening portion of the chapter; the result says so in its truncated flag and provenance note. Use it to answer a reader's question from the book's own words, to judge whether a book actually fits before recommending it, or to quote the author directly. Every book on the shelf has one.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The book slug, e.g. the-first-real-job. |
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 genuinely useful behavior: the chapter may be truncated for some samples, signaled via a truncated flag and provenance note, and the tool returns prose rather than a summary. That disclosure of partial results is the kind of 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 what the tool returns and why, and each sentence adds information (content, companion metadata, truncation caveat, use cases). Slightly dense but no filler sentences.
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 return-value burden and does so well: chapter prose, coverage, length, full chapter list, where to get the rest, and the truncated flag. An agent knows what it will receive.
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 the single slug parameter with an example. The description adds nothing about slug format or resolution, so 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?
States a specific verb and resource — 'the text of chapter one of any Greenlit book' — and explicitly contrasts with what it is not (not a summary, not a sales page). An agent can distinguish it from get_book or find_answer_in_books from the description alone.
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 three concrete usage scenarios: answering a reader's question from the book's own words, judging fit before recommending, and quoting the author. No explicit exclusion or named alternative sibling, so it stops short of a 5, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One Greenlit series with its books in reading order. Use for questions like where to start with Claude Code or what order to read a series in.
| Name | Required | Description | Default |
|---|---|---|---|
| series | Yes | The series slug. |
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 and determinism are covered. The description adds only that output is a single series in reading order; it says nothing about empty/missing series behavior or result size. Adequate but thin 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?
Two short sentences, front-loaded with the resource and then the use case. No filler, though the example phrasing is slightly verbose relative to the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, closed-world, read-only lookup with no output schema, the description supplies enough to call it correctly; the return shape is implied by 'books in reading order'. Only edge-case behavior is 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% with a 13-value enum and a 'series slug' description, so the schema already carries the parameter meaning. The description adds no syntax or format guidance beyond that 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 resource (one Greenlit series with its books) and the ordering guarantee (reading order). It is clearly distinct from lookup siblings like get_book or search_greenlit_books, though it does not name a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases ('where to start with Claude Code', 'what order to read a series in'), which tells the agent the intended question shape. No explicit when-not or named alternative, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks whether an AI agent, MCP server, coding tool or AI product is safe to use or how to set it up safely, or wants a reading on a subject these pages cover. Searches everything on greenlitbooks.com: safety verdicts on AI agents, MCP servers and coding tools ("is X safe"), field notes, guides, and the books. Returns ids to pass to fetch, each with its title and URL.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look for, e.g. "is cursor safe" or "prompt injection". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses the return shape (ids to pass to fetch, each with title and URL) and the downstream chaining 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?
Two sentences, front-loaded with the usage trigger before the scope and return-value details. The first sentence is somewhat long and clause-heavy, but no sentence is redundant or 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 correctly compensates by explaining the return values and their purpose (ids for fetch). For a single-parameter read-only search this is nearly complete; the one missing piece is disambiguation from the overlapping sibling search_greenlit_books.
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?
There is a single parameter with 100% schema coverage and concrete examples ('is cursor safe', 'prompt injection'), so the schema carries the semantic load. The description adds scope ('searches everything on greenlitbooks.com') but no format or syntax guidance beyond what the schema already supplies, which is the expected baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Searches everything on greenlitbooks.com') and enumerates the content it covers (safety verdicts, field notes, guides, books). It does not, however, distinguish itself from the similarly named sibling search_greenlit_books, leaving the agent to guess which search tool is authoritative.
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 opening clause gives a clear trigger ('when someone asks whether an AI agent, MCP server, coding tool or AI product is safe to use or how to set it up safely'). It stops short of naming when NOT to use it or pointing to alternatives such as find_books_for_topic or search_greenlit_books.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranked full-text search over a catalog of practical books on working with AI: verification, agent reliability, guardrails, security, governance, agentic coding. Returns scored results with title, description, series, and links. Follow a result's apiUrl or call get_book for the full record.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | The search query. | |
| limit | No | Max results, default 10. | |
| series | No | Restrict to one series. | |
| audience | No | Restrict to one reader level. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds context beyond that: results are relevance-scored, and it enumerates the returned fields (title, description, series, links) plus the apiUrl follow-up path. It does not mention result caps or query behavior, but this is solid 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?
Three sentences, front-loaded with the core purpose, then the return shape, then the follow-up action. The topic enumeration is somewhat long but genuinely narrows the catalog scope. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description discloses scoring and the returned fields, and it routes the agent to get_book/apiUrl for the full record. Given a 4-parameter, enum-constrained search tool, this is nearly complete; only pagination/ordering controls are unaddressed, and the sibling routing gaps keep it from a 5.
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%, covering q, limit (max 25, default 10), series, and audience, so the schema carries the parameter burden. The description only references 'series' incidentally as a returned field and adds no filtering syntax or semantics beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('ranked full-text search over a catalog of practical books') and scopes the domain with a concrete topic list (verification, guardrails, governance, agentic coding). It is clear what the tool does, but it never distinguishes itself from sibling search tools such as 'search' or 'find_books_for_topic', so the agent must infer which is appropriate.
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 follow-up routing ('Follow a result's apiUrl or call get_book for the full record'), which is real usage guidance for the next step. However it says nothing about when to choose this over the sibling 'search' or 'find_books_for_topic' tools, so selection guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_answer_in_booksfetchsearchcheck_claim1 field changedInput schema / properties / statement / descriptionPrevious value: -"What you want to check, in your own words, e.g. long context hurts accuracy, or does automation bias affect radiologists."New value: +"What you want to check, in your own words. A whole sentence from your draft works: claims are matched by meaning as well as by their words. E.g. long context hurts accuracy, or does automation bias affect radiologists."cite_source4 fields changedInput schema / properties / part / descriptionPrevious value: -"Which thing is being cited. Defaults to book, or to term when the slug is a glossary term."New value: +"Which thing is being cited, when using slug. Defaults to book, or to term when the slug is a glossary term."Input schema / properties / slug / descriptionPrevious value: -"A book slug (e.g. blast-radius) or a glossary term slug (e.g. gate-faith)."New value: +"A book slug (e.g. blast-radius) or a glossary term slug (e.g. gate-faith). Use url instead when you have one."Input schema / properties / urlAdded value: +{
+ "description": "The url you are about to quote, fragment included, e.g. https://greenlitbooks.com/book/blast-radius#claim-2 or /book/blast-radius/read#the-costume. Preferred: it cites the fragment, not the page.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "slug"
-]get_reading_path1 field changedInput schema / properties / series / enumPrevious value: -[
- "the-operators-ai-library",
- "the-ai-native-builder-canon",
- "understand-and-trust-ai",
- "build-agents-you-can-trust",
- "lead-govern-and-apply-ai",
- "ai-and-agentic-engineering",
- "the-claude-code-ladder",
- "the-agent-builders-workshop",
- "the-two-doors",
- "forward-deployed-engineering-handbooks",
- "the-complete-grok-bot-guide",
- "the-omarchy-books"
-]New value: +[
+ "the-operators-ai-library",
+ "the-ai-native-builder-canon",
+ "understand-and-trust-ai",
+ "build-agents-you-can-trust",
+ "lead-govern-and-apply-ai",
+ "ai-and-agentic-engineering",
+ "the-claude-code-ladder",
+ "the-agent-builders-workshop",
+ "the-two-doors",
+ "forward-deployed-engineering-handbooks",
+ "the-complete-grok-bot-guide",
+ "the-omarchy-books",
+ "the-personal-ai-computer"
+]search_greenlit_books1 field changedInput schema / properties / series / enumPrevious value: -[
- "the-operators-ai-library",
- "the-ai-native-builder-canon",
- "understand-and-trust-ai",
- "build-agents-you-can-trust",
- "lead-govern-and-apply-ai",
- "ai-and-agentic-engineering",
- "the-claude-code-ladder",
- "the-agent-builders-workshop",
- "the-two-doors",
- "forward-deployed-engineering-handbooks",
- "the-complete-grok-bot-guide",
- "the-omarchy-books"
-]New value: +[
+ "the-operators-ai-library",
+ "the-ai-native-builder-canon",
+ "understand-and-trust-ai",
+ "build-agents-you-can-trust",
+ "lead-govern-and-apply-ai",
+ "ai-and-agentic-engineering",
+ "the-claude-code-ladder",
+ "the-agent-builders-workshop",
+ "the-two-doors",
+ "forward-deployed-engineering-handbooks",
+ "the-complete-grok-bot-guide",
+ "the-omarchy-books",
+ "the-personal-ai-computer"
+]check_claimcite_sourcedefine_termfind_books_for_topicget_bookget_conceptget_free_chapterget_reading_pathsearch_greenlit_booksSearch and read 550+ free AI course tracks and 21,000+ lessons, so answers can cite a real lesson.
Book discovery using an AI-curated book catalog that eliminates hallucinations and surfaces lesser-known titles.
Verified summaries of business books, articles and reports for workplace learning and AI upskilling
AI-curated book catalog that eliminates hallucinations and surfaces lesser-known titles.
Add one secure layer between your agents and this server.