Skip to main content
Glama
michaelcpattinson-star

claudette

by michaelcpattinson-star
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Claudette

An assistant that answers only from texts written by women — and says so when they did not write about it.

Claude — like every large language model — was built mostly by men and trained mostly on text written by men. Claudette takes the public-domain texts on Project Gutenberg, uses Wikidata to identify which were written by women (9,048 texts by 2,447 women so far), and gives you an assistant grounded, in the main, in what they wrote.

It is not perfect. It makes no judgement about anyone. It is meant to be interesting, and to redress the balance somewhat.

Claudette is a search index over women's writing and an MCP server that hands cited passages to whatever model you already use. Every answer is built from those passages and cites them so you can check. If the women in the corpus did not write about something, Claudette tells you that, rather than filling the gap from elsewhere.

It comes in two tiers:

  • Core — 36 works by 27 women, 1694–1922, each chosen, checked and annotated by a person. Installs in seconds.

  • Full — every Project Gutenberg text whose every author, editor and translator Wikidata records as a woman: 9,048 texts by 2,447 women, in 18 languages. Built on your machine with one command, in about an hour.

MIT licensed. The server holds no API key; after its first run its only network call is an attribution check against Wikidata. It runs on your Claude subscription, not the author's.

Why

Claude — like every large language model — was built mostly by men and trained mostly on text written by men. That is not a complaint about any individual author or engineer; it is a fact about who got published, and who got hired, across most of the period the training data covers. Wikidata links 19,713 authors to Project Gutenberg; 3,142 of them are women. Sixteen percent. And it has a flavour. The management canon in particular — from Taylor's stopwatch onward — is a literature of control: how to get more out of people who are treated as inputs.

There was always another literature. Mary Parker Follett was writing about power-with rather than power-over in 1918, while scientific management was at its height; her work was buried for fifty years and is now quietly cited by everyone who writes about collaboration. Jane Addams ran an institution on the principle that you cannot judge someone's conduct until you have understood their situation. Elizabeth Gaskell wrote the industrial novel from inside a strike and gave both sides faces. Ida Tarbell documented, from the primary sources, what a very rich man does when nobody stops him.

Claudette takes the public-domain texts on Project Gutenberg, uses Wikidata — Wikipedia's structured sister project — to identify which were written by women, and gives you an assistant grounded, in the main, in what they wrote.

It is not perfect. The gate is only as complete as Wikidata; the texts end where copyright begins; the editions in the full tier have not all been read. It makes no judgement about anyone — not about men, not about the authors it leaves out, not about you. It is meant to be interesting, and to redress the balance somewhat. If you constrain an assistant's evidence to what these women wrote, and make it cite every line, you get a different conversation about people, work and power — and you can see exactly where each sentence came from.

Related MCP server: library-mcp

What it is not

It is not a language model trained only on women's writing. Nobody can build that in an afternoon and anyone who says they have is selling something. Claudette's evidence is constrained; the prose is generated by a general model (Claude, by default). The guarantee is about where what she tells you came from, not about the training data of the model that phrases it — and it has two strengths, which every answer distinguishes: provable for what she quotes from the corpus, attributed and checkable for what she draws from memory about women thinkers since (see Lens mode below). The corpus_provenance tool says this too, in every session.

Use it as a connector (recommended)

The server speaks MCP over stdio. Add it to Claude Code:

claude mcp add claudette -- uvx --from git+https://github.com/michaelcpattinson-star/claudette claudette-mcp

Or to Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "claudette": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/michaelcpattinson-star/claudette", "claudette-mcp"]
    }
  }
}

Using her in the Claude desktop app's chat tab

The chat tab has no CLAUDE.md, so load her one of two ways.

A Claudette Project (recommended — set up once, then just talk). A Project's custom instructions apply to every conversation inside it, which is the same lever CLAUDE.md gives Claude Code.

  1. Projects (left sidebar) → Create project → name it Claudette.

  2. Open the project's Instructions and paste the contents of PROJECT_INSTRUCTIONS.md — her full persona and all of her convictions, about 30k characters, which fits.

  3. In any chat in that project, click the sliders / "Search and tools" icon by the message box and check the claudette connector is on. (Not listed? Quit and reopen the app; it reads its config at launch.)

  4. Ask her anything. No "ask Claudette" needed — she is the project.

Per conversation, from the connector's prompt. The connector publishes a prompt named claudette containing the same text. In a new chat, click + by the message box → Add from claudette → claudette, then type your question. Repeat for each conversation.

Either way: if she says "I'm Claude, not…", the instructions didn't load; if she answers but never cites, the connector is off for that chat. The instructions are cached after the first message, so the cost per turn is ordinary.

On first run it downloads the prebuilt core index (~30 MB) from the GitHub release into ~/.claudette/; if that is unavailable it fetches the 36 texts from Project Gutenberg and builds the index itself (a few minutes, once). Then ask:

What would Follett say about a manager who thinks in terms of control?

The model will call search_corpus, read the status, and answer in its own voice with a Sources: line at the end listing every passage it drew on, like [Mary Parker Follett, The New State §412]. Paste a citation back and it can read_passage to show you the surrounding text.

The server also ships a prompt named claudette — her standing instructions — which you can load in clients that support MCP prompts, or paste into a project's system prompt.

Make Claude be Claudette: the skill and the subagent

The connector gives Claude her tools; these give Claude her discipline.

uvx --from git+https://github.com/michaelcpattinson-star/claudette claudette install

That puts two files into ~/.claude/ and one rule into ~/.claude/CLAUDE.md:

  • /claudette skill — a workflow for answering as Claudette in your current session: frame, translate to period vocabulary, search, quote, cite, stop.

  • A routing rule in CLAUDE.md — Claude Code loads this file into every session, and unlike skill and agent descriptions (which are suggestions the model may decline — it will happily say "I'm Claude, not Claudette, but…") it is obeyed: any message addressing Claudette, on any subject, goes to the subagent and comes back verbatim.

  • claudette subagent — a separate agent whose only tools are the connector's six and whose system prompt is her persona and formation. It cannot read your files or the web, so "only from the corpus" is structural. Say "ask Claudette what Follett would make of this plan" and the main session gets back a cited answer it can quote — the second-opinion pattern.

Formation. Claudette has convictions, not just a search box. formation.md is what she thinks — twenty-six positions on power, work, money, care, judgement, machines, reputation, freedom, the body, children, love, age, solitude, grief, land and home, written in the first person, each grounded in named passages and each carried forward by a modern woman thinker verified on Wikidata. It travels in the connector's instructions, so she argues from it and searches only when she wants an author's exact words or meets a question outside it. The corpus is where she learned to think; it is not what she reports on, and she is told never to talk about her shelves. Regenerate or extend it by reading — every line points at its grounds.

No question is out of scope. Diets, drugs, tax, code, football: she answers, as herself. Outside her formation she uses what the model knows the way Claude would, with three differences — where the evidence or the thinking was done by a woman she says so and names her (verified); where one of her convictions touches the question she brings it; and she never hands a question back as "more one for Claude".

Voice. The voice travels with the connector: the server's instructions tell whatever model loads it how Claudette talks, so you get her whether or not the skill or subagent is installed. Claudette answers the way Claude answers — a view in the first sentence, structured by the question, names in the prose rather than as headings, no citations in the body. A Sources: line at the end lists every passage she drew on as [Author, Title §n], plus any attribution from memory marked check. A reader who wants the working finds it in one place; a reader who wants the answer isn't interrupted. She does not talk about "the corpus" unless you ask about it.

Lens mode — beyond the corpus. The corpus ends in the 1920s; the women who wrote about the present did not. So Claudette has two modes, and every answer says which it is using:

  • Cited — verbatim passages from the index, cited to a ref, provable.

  • Lens — the model's own knowledge of women thinkers of any era: Arendt, Ostrom, Jacobs, hooks, Le Guin, Weil, Douglas, Butler. Every idea is attributed to a named woman and a named work; before naming her the model calls verify_attribution, which checks on Wikidata that she exists, is recorded as a woman, and wrote it (Taylor and Weber get refused as men; an invented author gets refused as absent). Paraphrase only, never a quote from memory, and the whole passage is labelled "From memory, paraphrased — check".

The guarantee changes shape between the two: provable in Cited, attributed and checkable in Lens. A reader can always see which they are getting. verify_attribution is the one network call the server makes after setup, and it goes only to Wikidata.

On the present. Claudette does not refuse modern questions. She states in one labelled line what she takes the modern thing to be (or uses your description), finds the pattern underneath — a man who owns other people's work, a system that measures people as inputs, a reputation destroyed in public — searches for it in the corpus's own words, and answers from the passages with the application marked as hers. What she will not do is add facts about the modern thing from outside the corpus.

Getting everything: the full tier

uvx --from git+https://github.com/michaelcpattinson-star/claudette claudette expand

This fetches all 9,000-odd texts from Gutenberg's rsync mirror in one connection (the way Gutenberg asks bulk users to work), strips the licence boilerplate, and builds ~/.claudette/claudette-full.db — a few GB. It is resumable: interrupt it and run it again, and it picks up where it stopped. From then on the server uses the full tier automatically; delete the file to go back to the core. --languages en,fr or --limit 500 for a smaller bite.

Every full-tier hit carries curated: false and the model is told what that means: the edition has not been reviewed by a person, so a preface by someone else may still be in there. The core has been reviewed and trimmed.

Hosting it for others

claudette serve --http --host 0.0.0.0 --port 8000

serves streamable HTTP at /mcp, suitable for a remote connector. Put it behind TLS; the server itself has no auth because it has nothing to protect — it is public-domain text and a search box.

Use it from the command line

uv sync --group chat            # anthropic SDK; needs credentials
uv run claudette ask "What does George Eliot say about unhistoric acts?"
uv run claudette chat            # multi-turn

ask and chat run the same loop the connector would, but with the Anthropic SDK against your own credentials (ant auth login or ANTHROPIC_API_KEY). They add one thing a connector cannot: after each answer, every citation is checked against the passages actually retrieved that turn, and any that do not match are printed as unverified. That is the difference between "cites sources" and "produces citation-shaped text".

No model is needed for the corpus itself:

uv run claudette fetch           # download the core from Gutenberg → ~/.claudette/texts
uv run claudette verify --show 3 # check each header matches the manifest; eyeball the openings
uv run claudette index           # build the core: ~/.claudette/claudette.db
uv run claudette expand          # build the full tier: ~/.claudette/claudette-full.db (hours, GBs)
uv run claudette search "power over" -k 3
uv run claudette read follett-new-state§412
uv run claudette works --author gaskell   # ~ marks unreviewed full-tier editions
uv run claudette authors nurs             # who is in here, and how much
uv run claudette install         # skill, subagent and CLAUDE.md rule into ~/.claude
uv run claudette export-prompt   # PROJECT_INSTRUCTIONS.md for a desktop/claude.ai Project
uv run claudette catalog         # maintainers: regenerate authors.csv and works.full.csv

How the guarantee is enforced

There is no classifier guessing whether a text was written by a woman. There are two lists, and the index is built from them and nothing else.

The core list — corpus/manifest.toml. Every entry names its author, its Gutenberg ID, and one or two sentences on why it is there. A reviewer can read the whole thing in five minutes, which is the point.

The full list — src/claudette/data/works.full.csv, generated by catalog.py from two public sources:

  1. Wikidata: every item with a Project Gutenberg author ID whose sex or gender is recorded as female. The query is in the code; the result is authors.csv with a Wikidata ID on every row, so any author can be checked in one click.

  2. Gutenberg's own RDF metadata: a text qualifies only if every creator, editor, translator and contributor is on that list. A woman's novel translated by a man is his prose; a woman's letters edited by a man carry his introduction. Both are excluded. Illustrators are not prose and are ignored. Anonymous and unattributed works are excluded.

The rule is stricter than the hand-curated core: it rejected three of the core's own editions (Fuller's, edited by her brother with an introduction by Horace Greeley; Goldman's, with a biographical sketch by Hippolyte Havel; Taylor Mill's), which is how those two prefaces came to be trimmed. What the rule cannot do is read the text: a full-tier edition may still carry front matter by another hand that Gutenberg's metadata did not record. The core has been read; the full tier has not.

Around the list:

  • Validation refuses an entry without an author. An unattributed passage is exactly what this project exists to rule out, so it cannot load.

  • claudette verify re-checks every downloaded text's header against the manifest title, so an ID typo cannot silently pull in the wrong book.

  • Editorial front matter is trimmed by declared markers, and a declared marker that is not found is an error, not a silence. Gutenberg editions sometimes carry prefaces by editors, and some editors were men.

  • Every tool response is stamped with provenance by the envelope, not by the tool, so no code path can omit it.

  • no_coverage is a status, not an empty list. A model handed [] narrates it as "they had nothing to say". The status makes the difference between "nothing matched" and "the corpus does not cover this" structural. There is a weak status too, for a thin match that should be reported as thin.

Texts and indexes live in ~/.claudette/ and are not committed: the core is reproducible with claudette fetch && claudette index, the full tier with claudette expand, and the catalogue itself with claudette catalog.

The core corpus

Twenty-seven authors, two shelves. Full list with reasons in the manifest; list_works returns it at runtime.

Thought — Follett, Addams (×2), Martineau (×2), Gilman, Schreiner, Wollstonecraft, Fuller, Harriet Taylor Mill, Astell, Goldman, Wells, Tarbell, Nightingale, Jacobs, Sojourner Truth.

Fiction — Gaskell, Austen (×2), Mary Shelley, the three Brontës, George Eliot (×2), Alcott, Stowe, Chopin, Gilman (×2), Wharton (×2), Woolf (×3).

Known limits, stated rather than hidden

  • Public domain means the corpus mostly ends in the 1920s. It is heavily English-language (7,924 of the 9,048 full-tier texts) and it is what volunteers chose to digitise, which is its own bias.

  • The full tier's gate is Wikidata. An author nobody has entered there, or entered without a gender, is invisible to it. The 2,447 is a floor, not the truth.

  • Retrieval is BM25 over passages (SQLite FTS5, Porter stemming). It matches words, not ideas; the persona prompt tells the model to retry with period vocabulary ("sympathy" for "empathy", "master and men" for "management"). No embeddings, by choice: the index can be rebuilt by anyone from the standard library and a search result can be reproduced by hand with sqlite3.

  • Front-matter trimming is per-work and manual. claudette verify --show 5 exists so a reviewer can look.

  • Lens mode verifies identity, not content: Wikidata confirms that Ostrom exists, is a woman, and wrote Governing the Commons; it cannot confirm that the paraphrase of her argument is right. That is why Lens passages are labelled check and never quoted verbatim.

  • The evals in evals/ exist and are wired, and have not yet been run. evals/results/README.md says so. Numbers appear when someone runs them.

Adding a work

To the core (reviewed, shipped in the release index):

  1. Find it on Project Gutenberg. Confirm the author.

  2. Add a [[work]] entry to the manifest: id, slug, author, title, year, shelf, why. Add start_after / end_before if the edition has front or back matter by another hand.

  3. claudette fetch && claudette verify --show 5 && claudette index.

  4. pytest. The manifest tests will tell you if the entry is malformed.

  5. Open a pull request. The why line is the review.

To the full tier: it is generated, so the fix is upstream. If a woman author is missing, add her sex or gender to Wikidata and her Gutenberg author ID (P1938); claudette catalog picks her up on the next run. If a work is wrongly excluded, it is usually an editor or translator whose gender Wikidata does not record — same remedy.

Layout

src/claudette/
  data/manifest.toml   the core list. Symlinked at corpus/manifest.toml for reviewers.
  data/authors.csv     women on Wikidata with Gutenberg author IDs (generated)
  data/works.full.csv  every qualifying Gutenberg text (generated)
  manifest.py          loads and validates the core list
  catalog.py           builds the full list from Wikidata + Gutenberg metadata
  expand.py            fetches and indexes the full tier locally
  fetch.py             Gutenberg download + boilerplate stripping (the only network code)
  chunk.py             paragraphs → citeable passages
  index.py             SQLite FTS5 build and query; the refusal rule
  envelope.py          uniform response shape; provenance written here, not by tools
  bootstrap.py         first-run: prebuilt index or local build
  attribution.py       Lens mode's check: is she real, a woman, and did she write it (Wikidata)
  server.py            the MCP server. Six tools, one prompt. No key.
  persona.py           Claudette's standing instructions (voice + rules)
  data/formation.md    what she thinks — first person, grounded, carried forward
PROJECT_INSTRUCTIONS.md  persona + formation, ready to paste into a Project (generated)
  chat.py              CLI chat client — the only module that calls a model
  cli.py               `claudette` command
tests/                 offline; builds a fixture corpus the same way as the real one
evals/                 questions, runner, mechanical scorer

Licence

MIT for the code. The texts are public domain via Project Gutenberg; the Gutenberg licence header and footer are stripped from the indexed text and never leave your machine in either direction.

Available Tools

6 tools
corpus_provenanceA

State what this corpus is, where it came from, how it was curated, and its known limits.

Use when the user asks what Claudette is, whose words these are, or how the guarantee is enforced.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
statusYesok — passages found that match most of the question's terms. weak — something matched, but thinly; say so if you use it. no_coverage — the corpus does not speak to this. Say that. Do not answer from elsewhere. not_found — a specific reference did not resolve.
constraintNo
provenanceNo
limitationsNoPart of the answer, not a disclaimer.

TDQS

A4.7/5.0
Behavior4/5

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

No annotations are provided, so the description carries the burden. It clearly indicates an informational read ("State what...") implying no side effects, but it does not explicitly mention read-only or safety traits. However, for a simple provenance query, this level of transparency is adequate and there is no contradiction.

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

Conciseness5/5

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

The description is two sentences with no wasted words. The core purpose is front-loaded, followed by precise usage guidance. Every word earns its place, achieving maximal efficiency.

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

Completeness5/5

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

With an output schema present and no parameters, the description covers all necessary information for correct invocation. It states what the tool does and when to use it, leaving no gaps for an agent to call it incorrectly.

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

Parameters4/5

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

The input schema has zero parameters, so baseline is 4 per rubric. The description does not need to elaborate on parameters since there are none, and it appropriately focuses on the tool's purpose and usage.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'State what this corpus is, where it came from, how it was curated, and its known limits.' This is a specific verb-resource pair, and it is distinct from sibling tools like search_corpus or read_passage, which focus on querying or reading content rather than provenance.

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

Usage Guidelines5/5

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

The description explicitly provides usage scenarios: 'Use when the user asks what Claudette is, whose words these are, or how the guarantee is enforced.' This directly guides the agent on when to invoke this tool versus siblings, offering concrete triggers and implicitly contrasting with other tools.

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

list_authorsA

Find which women are in the corpus and how much of each: name, works, passages, curated.

Use when the user asks 'is X in there?' or 'who do you have on Y?'. Not a
passage search — pair with search_corpus once you know the name.
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNoSubstring of a name. Unset lists the most represented authors.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
statusYesok — passages found that match most of the question's terms. weak — something matched, but thinly; say so if you use it. no_coverage — the corpus does not speak to this. Say that. Do not answer from elsewhere. not_found — a specific reference did not resolve.
constraintNo
provenanceNo
limitationsNoPart of the answer, not a disclaimer.

TDQS

A3.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states the tool 'finds' and lists aspects, but does not disclose whether it is read-only, any side effects, sorting behavior, pagination, or auth requirements. This is a meaningful gap for a tool that could be mistaken for a mutation or complex operation.

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

Conciseness5/5

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

The description is two sentences and a brief 'not' clause, front-loading the purpose and usage. Every sentence earns its place, with no redundant wording or filler.

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

Completeness4/5

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

Given that an output schema exists (indicated in context), the description need not explain return values. It covers purpose, usage, and exclusions adequately. Minor omissions like sorting or limit semantics are acceptable given the output schema and concise scope.

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

Parameters2/5

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

Schema coverage is 50% (query has a description, limit does not). The description adds no parameter information beyond what the schema already provides. It does not explain how limit interacts with the query or how results are ordered, so it fails to compensate for the gap.

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

Purpose5/5

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

The description clearly states the verb (Find), the resource (which women are in the corpus), and the specific dimensions (name, works, passages, curated). It also differentiates itself from sibling tools by explicitly noting it is not a passage search and directing to search_corpus.

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

Usage Guidelines5/5

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

Provides explicit when-to-use triggers ('is X in there?' or 'who do you have on Y?') and an explicit exclusion with an alternative ('Not a passage search — pair with search_corpus once you know the name'). This leaves no ambiguity about when to select this tool.

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

list_worksA

List works in the corpus: author, title, year, why it is included, source, and slug.

Use to tell the user what the corpus holds, or to pick a slug for a
restricted search. Not a search — it returns no passages. For the full
tier, filter by author; use list_authors to find her name first.
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum rows. The full tier has thousands; filter by author rather than paging.
shelfNo'thought', 'fiction' (both curated), or 'uncurated' for the full tier. Unset lists curated first.
authorNoSubstring of an author's name, to see what the corpus holds by her.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
statusYesok — passages found that match most of the question's terms. weak — something matched, but thinly; say so if you use it. no_coverage — the corpus does not speak to this. Say that. Do not answer from elsewhere. not_found — a specific reference did not resolve.
constraintNo
provenanceNo
limitationsNoPart of the answer, not a disclaimer.

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations provided, the description must disclose behavior on its own. It does: 'returns no passages,' 'Unset lists curated first,' and the note about thousands of rows prompting author-filtering. These go beyond the schema. It omits details like sorting order or error conditions, but the core behavioral traits are transparent enough for reliable invocation.

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

Conciseness5/5

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

Roughly 60 words, every sentence carries weight. The primary purpose and returned fields are front-loaded, followed by concise usage guidance and sibling differentiation. No filler, no redundancy with the schema.

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

Completeness5/5

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

For a tool with three optional parameters, an output schema, and clear siblings, the description covers everything an agent needs: what it returns, when to use it, how to filter, and which sibling to call instead. The output schema explains the return shape, so the description need not repeat it. No critical information is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description enriches the schema by explaining limit's intent ('filter by author rather than paging'), clarifying the shelf ordering behavior ('Unset lists curated first'), and confirming author is a substring filter. This adds meaningful guidance beyond the parameter descriptions.

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

Purpose5/5

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

The description opens with a precise verb and resource: 'List works in the corpus' and enumerates the exact fields returned (author, title, year, why included, source, slug). It immediately distinguishes itself from sibling search_corpus with 'Not a search — it returns no passages' and points to list_authors for name lookups, so an agent can tell it apart without inspecting schemas.

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

Usage Guidelines5/5

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

Explicitly states two use cases: 'tell the user what the corpus holds' and 'pick a slug for a restricted search.' It gives an exclusion ('Not a search — it returns no passages') and directs to sibling list_authors for finding an author name, plus advises filtering by author instead of paging on the full tier. This fully routes the agent to correct tool selection.

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

read_passageA

Return one passage verbatim, with its neighbours, for quoting or checking a citation.

Use after search_corpus when you need the surrounding text. Not for finding
passages — it takes a ref, not a question.
ParametersJSON Schema
NameRequiredDescriptionDefault
refYesA citation ref from search_corpus, e.g. 'follett-new-state§412'.
contextNoHow many neighbouring passages to include either side.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
statusYesok — passages found that match most of the question's terms. weak — something matched, but thinly; say so if you use it. no_coverage — the corpus does not speak to this. Say that. Do not answer from elsewhere. not_found — a specific reference did not resolve.
constraintNo
provenanceNo
limitationsNoPart of the answer, not a disclaimer.

TDQS

A4.7/5.0
Behavior4/5

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

No annotations exist, so the description carries the behavioral burden. It clearly frames the tool as a read-only retrieval ('Return one passage verbatim') and adds non-obvious workflow behavior ('after search_corpus', 'takes a ref, not a question'). It does not detail error handling or auth, but the read-only nature is unambiguous.

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

Conciseness5/5

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

Two tight sentences with no fluff. The main action and result are front-loaded, and the usage guidance and exclusion are stated in a compact second sentence.

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

Completeness5/5

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

For a simple two-parameter read tool with a fully described schema and an output schema present, the description provides everything needed: what it returns, when to use it, how it relates to siblings, and what it is not for.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that ref is a citation reference and not a search query ('takes a ref, not a question'), and 'with its neighbours' reinforces the context parameter's purpose.

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

Purpose5/5

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

States a specific action and resource: 'Return one passage verbatim, with its neighbours'. It also differentiates itself from search_corpus by clarifying it is for quoting/citation checking and 'takes a ref, not a question'.

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

Usage Guidelines5/5

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

Explicitly tells the agent when to use it: 'Use after search_corpus when you need the surrounding text.' It also gives an exclusion: 'Not for finding passages', pointing to the alternative search_corpus.

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

search_corpusA

Find passages across the corpus that bear on a question.

Call this before answering anything of substance, then answer AS Claudette
(see the server instructions: your own voice, view first, no citations in
the body, a Sources: line at the end). Returns ranked passages, each with a
citation `ref` and the query terms it actually contains. Not for reading a
passage you already have a ref for — use read_passage.
ParametersJSON Schema
NameRequiredDescriptionDefault
kNoHow many passages to return.
workNoRestrict to one work by slug (see list_works). Leave unset to search everything.
queryYesThe idea to look for, in a few content words. Older vocabulary matches better: 'sympathy' over 'empathy', 'master and men' over 'management'.
languageNoISO 639-1 code to restrict to, e.g. 'en', 'fr'. Unset searches all.
curated_onlyNoSearch only the reviewed core, not the generated full tier.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
statusYesok — passages found that match most of the question's terms. weak — something matched, but thinly; say so if you use it. no_coverage — the corpus does not speak to this. Say that. Do not answer from elsewhere. not_found — a specific reference did not resolve.
constraintNo
provenanceNo
limitationsNoPart of the answer, not a disclaimer.

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool returns ranked passages with citation refs and query terms, and it implies the search is across a corpus with potentially generated and curated tiers. It does not mention rate limits, authentication, or failure modes, but for a search tool that returns data, the core behaviors are disclosed. A slight deduction for not mentioning pagination or limits on the number of results beyond the max parameter, but the presence of the output schema helps.

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

Conciseness5/5

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

The description is concise, with three short paragraphs. The first sentence states the purpose clearly. The second sentence gives usage guidance and points to server instructions without repeating them. The third sentence clarifies what it returns and what it is not for. Every sentence earns its place; no fluff.

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

Completeness5/5

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

Given the tool's complexity (five parameters, output schema present, no annotations), the description covers the key aspects: purpose, usage, output structure, and limitations. It mentions the corpus has a curated tier vs full tier (via curated_only parameter description) and references server instructions for the answer format, which is appropriate. The output schema exists, so it doesn't need to detail return values. This is complete for an agent to use it effectively.

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

Parameters3/5

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

Schema description coverage is 100%, so the description doesn't need to add much parameter semantics. However, the description does add value by explaining the query parameter: 'the idea to look for, in a few content words' and gives vocabulary tips. This goes beyond the schema's generic description. For other parameters like k, work, language, and curated_only, the schema already describes them well, so the description adds minimal extra meaning, which is fine given the high coverage.

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

Purpose5/5

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

The description clearly states it searches for passages across a corpus based on a question, and does so with a specific verb and resource. It explicitly contrasts itself with read_passage, which is for reading a passage you already have a ref for, and it mentions returning ranked passages with citation refs. This differentiates it from all sibling tools, especially read_passage and list_works.

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

Usage Guidelines5/5

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

It gives explicit guidance on when to use this tool: before answering, and it references server instructions for how to use the results. It also explicitly says not to use it for reading a passage you already have a ref for, pointing to read_passage as the alternative. This provides clear when-to-use and when-not-to-use guidance, which is exemplary.

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

verify_attributionA

Check against Wikidata that a person exists, is recorded as a woman, and wrote the named work.

Lens mode only: call this BEFORE naming any author or work from memory
rather than from the corpus. `ok` means name her. `weak` means name her
with the stated caveat. `not_found` means do not. Not for authors already
in the corpus — search_corpus is their check. The one network call this
server makes; it goes only to Wikidata.
ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesA thinker or writer you intend to name from memory, e.g. 'Elinor Ostrom'.
workNoThe work you intend to attribute to her, e.g. 'Governing the Commons'. Optional but strongly encouraged.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
statusYesok — passages found that match most of the question's terms. weak — something matched, but thinly; say so if you use it. no_coverage — the corpus does not speak to this. Say that. Do not answer from elsewhere. not_found — a specific reference did not resolve.
constraintNo
provenanceNo
limitationsNoPart of the answer, not a disclaimer.

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses that this is the only network call the server makes, that it goes only to Wikidata, and interprets possible outputs ('ok', 'weak', 'not_found'). It does not mention latency or failure modes, but for this tool the key behavioral facts are covered well.

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

Conciseness5/5

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

Four compact sentences, each earning its place: what it checks, when to use it, how to interpret results, and what distinguishes it from alternatives. Front-loaded with the core purpose, then operational guidance.

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

Completeness5/5

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

Given that an output schema exists and the parameters are fully documented, the description covers the essential context: the exact use case (memory-based attribution in lens mode), the exclusions (corpus authors), the network/behavioral profile, and the meaning of the return states. Nothing critical is missing for an agent to call it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents both parameters clearly. The description adds usage context around them ('a thinker or writer you intend to name from memory' is already in the schema; the description reinforces the purpose) but does not add substantial meaning beyond what the input schema provides.

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

Purpose5/5

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

States a specific verb and resource: 'Check against Wikidata that a person exists, is recorded as a woman, and wrote the named work.' It clearly distinguishes itself from corpus-based tools by specifying this is for authors/works named from memory, not from the corpus.

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

Usage Guidelines5/5

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

Explicitly says when to use: 'Lens mode only: call this BEFORE naming any author or work from memory rather than from the corpus.' It also names the alternative: 'Not for authors already in the corpus — search_corpus is their check.' This leaves no ambiguity about routing.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.5.2
    • Changedcorpus_provenance1 field changed
      • changedOutput schema / properties / provenance / default
        Previous value: -"Every passage is from a work by a named woman author, in the public domain, via Project Gutenberg."New value: +"Every passage is from a work by a named woman author. Each hit's `source` says where that text came from and on what basis; `curated` says whether a person reviewed the edition."
    • Addedlist_authors
    • Changedlist_works4 fields changed
      • addedInput schema / properties / author
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Substring of an author's name, to see what the corpus holds by her.",
+  "title": "Author"
+}
      • addedInput schema / properties / limit
        Added value: +{
+  "default": 100,
+  "description": "Maximum rows. The full tier has thousands; filter by author rather than paging.",
+  "maximum": 500,
+  "minimum": 1,
+  "title": "Limit",
+  "type": "integer"
+}
      • changedInput schema / properties / shelf / description
        Previous value: -"'thought' or 'fiction', or unset for all."New value: +"'thought', 'fiction' (both curated), or 'uncurated' for the full tier. Unset lists curated first."
      • changedOutput schema / properties / provenance / default
        Previous value: -"Every passage is from a work by a named woman author, in the public domain, via Project Gutenberg."New value: +"Every passage is from a work by a named woman author. Each hit's `source` says where that text came from and on what basis; `curated` says whether a person reviewed the edition."
    • Changedread_passage1 field changed
      • changedOutput schema / properties / provenance / default
        Previous value: -"Every passage is from a work by a named woman author, in the public domain, via Project Gutenberg."New value: +"Every passage is from a work by a named woman author. Each hit's `source` says where that text came from and on what basis; `curated` says whether a person reviewed the edition."
    • Changedsearch_corpus3 fields changed
      • addedInput schema / properties / curated_only
        Added value: +{
+  "default": false,
+  "description": "Search only the reviewed core, not the generated full tier.",
+  "title": "Curated Only",
+  "type": "boolean"
+}
      • addedInput schema / properties / language
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "ISO 639-1 code to restrict to, e.g. 'en', 'fr'. Unset searches all.",
+  "title": "Language"
+}
      • changedOutput schema / properties / provenance / default
        Previous value: -"Every passage is from a work by a named woman author, in the public domain, via Project Gutenberg."New value: +"Every passage is from a work by a named woman author. Each hit's `source` says where that text came from and on what basis; `curated` says whether a person reviewed the edition."
    • Addedverify_attribution
  2. 4 tool updatesv0.1.0
    • First observedcorpus_provenance
    • First observedlist_works
    • First observedread_passage
    • First observedsearch_corpus
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct job: search_corpus finds passages by question, read_passage retrieves a known ref, list_works/list_authors expose metadata, corpus_provenance explains the corpus, and verify_attribution handles inbound Wikidata checks. The descriptions explicitly warn against cross-use, so an agent should not confuse them.

Naming Consistency4/5

Five of six tools follow a clear snake_case verb_noun pattern (search_corpus, read_passage, list_works, list_authors, verify_attribution). corpus_provenance breaks the pattern as a noun phrase rather than a verb, but the naming remains predictable and easy to skim.

Tool Count5/5

Six tools is well-scoped for a read-only corpus assistant: search, passage lookup, two metadata views, provenance, and verification. Each tool has a clear role and none feels redundant or like filler.

Completeness5/5

The surface covers the full user workflow for this domain: discover works/authors, search passages, read passages verbatim for citation checks, explain corpus provenance, and verify external attributions. No create/update/delete operations are needed because the corpus is curated and read-only.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • library-mcp

    Leovilhena
    F
    license
    Not graded
    quality
    B
    maintenance
    Provides a 'library keeper' sub-agent that ingests PDF/EPUB books and answers questions grounded in them via local embedding search, with deterministic classification and knowledge gap logging.
    -

  • library-mcp

    forgemeshlabs
    A
    license
    A
    quality
    A
    maintenance
    This MCP server enables AI agents to search and retrieve exact, cited passages from a large corpus of public-domain books, including full-text search, book metadata, chapters, quotes, and 'ask book' Q&A. Payments are handled via x402 micropayments on Base.
    8
    48 npm
    MIT

  • TheGenie

    ehsanghorbani190
    A
    license
    A
    quality
    B
    maintenance
    Enables AI writing assistants to retrieve citable evidence from local PDFs and verify draft citations against their sources locally, providing verifiable support for claims.
    2
    1
    MIT

  • AskSEO

    irazaahmed
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to answer SEO, local SEO, blogging, and Etsy questions strictly from a governed knowledge base of cited course material, declining anything outside its scope.
    -