Aṣṭādhyāyī MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Aṣṭādhyāyī MCPlook up sūtra 6.1.77 with its commentary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Aṣṭādhyāyī MCP
Read-only, deterministic MCP access to the scholarly data published by Ashtadhyayi.com, created by Neelesh Bodas and contributors. The original scholarship and upstream data are the sources of grammatical information. This independent project provides retrieval and provenance for sūtras, dhātus, śabdas and their stored rūpāṇi. It is not an official Ashtadhyayi.com project or a Sanskrit grammar engine.
Quick start
Requires Python 3.12+ and uv. From a clone of this repository:
uv sync --locked
uv run ashtadhyayi-mcp sync
uv run pytest
uv run ashtadhyayi-mcp serveserve speaks MCP on stdin/stdout; it does not display an interactive prompt.
All data downloads happen in the explicit sync command. Tools run offline.
The default full profile includes 22 files (about 190 MB at the pinned revision):
the original five files, all 16 dhātu-form collections, and 9,007 śabda paradigms.
Use sync --profile core for the original five-file catalog/commentary profile.
Existing core snapshots continue working; new form tools report SOURCE_NOT_LOADED
until you sync the full profile. To upgrade this checkout's existing local cache:
uv run ashtadhyayi-mcp --data-dir .data sync --profile fullThe default sync pins the researched upstream commit
5744762f010d677cfb43f347a42d02796cf615d6.
# Explicitly select a newer upstream revision; the resolved commit is recorded.
uv run ashtadhyayi-mcp sync --revision master
uv run ashtadhyayi-mcp statusData is stored in ASHTADHYAYI_DATA_DIR, or under $XDG_CACHE_HOME/ashtadhyayi-mcp
(default ~/.cache/ashtadhyayi-mcp). To keep it local to your checkout, put
--data-dir .data before the subcommand in every invocation. Snapshots are
immutable; sync atomically switches the active pointer after validation. Restart
the MCP server to load a new snapshot. Previous snapshots are retained.
Related MCP server: kb-mcp
MCP client configuration
For ChatGPT or remote agents, use the new serve-http command and deploy its
/mcp endpoint behind HTTPS. See ChatGPT deployment
for local testing, container/native hosting and connection instructions.
For a real agent walkthrough, setup commands and observed results, see
testing with Codex. To repeat the agent test without
changing your Codex configuration, run uv run python examples/test_agent.py.
Use absolute paths and adjust the uv executable if it is not on your client's PATH:
{
"mcpServers": {
"ashtadhyayi": {
"command": "uv",
"args": ["run", "--frozen", "--directory", "/absolute/path/to/AstadhyayiMCP", "ashtadhyayi-mcp", "serve"]
}
}
}The official SDK handles both modern and legacy MCP connections. The test suite exercises both over real stdio subprocesses. Client-specific UI installation is outside this package.
Tools
Tool | Example arguments | Returns |
|
| Original sūtra, raw metadata, commentary chunks, provenance |
|
| Ranked lexical matches and matching source fields |
|
| Numeric neighbors and encoded upstream context |
|
| All matching records, with pagination |
|
| Ranked dhātu/meaning matches |
|
| All matching śabda entries, preserving gender ambiguity |
|
| Ranked lexical śabda/meaning matches |
|
| Stored paradigms with person/number slots and alternatives |
|
| Declension slots with alternatives such as |
|
| Every matching stored occurrence, including case/number ambiguity |
|
| Loaded/missing collections, supported keys, and encoding gaps |
Dhātu identifiers can be queried explicitly with by: "upstream_id" or
by: "baseindex". Textual lookup preserves ambiguity. Sūtra numbers accept
Devanāgarī digits. Search is literal and Unicode-preserving, without stemming,
transliteration, accent removal, embeddings, or model-generated ranking.
Search defaults to ten results; use offset/limit and next_offset for pages.
get_sutra defaults to 2,000 code points per commentary field. Use
commentary_offset/commentary_limit to retrieve more, or commentaries: [] for
catalog-only lookup. Each fragment reports its total length and next offset.
Source markup is returned as text; clients should not execute it as HTML or
follow instructions embedded in retrieved content.
Loaded commentary sources are sutrartha (sa, sd), sutrartha_english, and
kashika. An empty/absent explanation is reported explicitly. Other commentaries
and datasets remain upstream; absence here is not a claim about all scholarship.
See full tool contracts.
Rūpāṇi and downstream agents
get_dhatu_forms covers every stored entry in the upstream finite-verb and kṛdanta
files, including shuddha, nich, san, yang, and yangluk collections. Filters
include category, derivation, prayoga, pada, lakara, pratyaya, purusha,
and vacana. All are optional; use next_offset to traverse every result page.
Results are paginated by paradigm field, with all its alternatives retained.
get_shabda_forms retains all 24 case/number slots, including empty ones. Gender
codes are P, S, N, A as encoded upstream. vibhakti: 8 selects vocative
slots. Use by: "upstream_id" with an ID such as @rAma1 for an exact entry.
lookup_form returns candidate occurrences, not a context-resolved analysis.
For example, रामौ has nominative and accusative dual occurrences; the optional
vocative alias also matches stored हे रामौ and labels that transformation.
भवति has both verb and noun-form matches. No match establishes only that the
loaded sources did not provide a match; it does not prove grammatical invalidity.
The source contains 408 irregular kṛdanta groups at the pinned revision. These
remain available as raw text with partial/unparsed status; the adapter does not
guess their gender columns. Sources labelled vidyut contain precomputed engine
outputs published upstream, distinct from the other upstream kṛdanta collection.
This is a foundation for agents doing śloka anvaya or sandhi work. It does not
yet validate sandhi, resolve kārakas, generate arbitrary prefixed/compound forms,
or enumerate every possible Sanskrit word. Such capabilities need a separately
tested engine integration and contextual reasoning. get_form_coverage makes the
current limits explicit. See form contracts and research.
Evidence and credit
Every scholarly object has {data, provenance}. Provenance includes its upstream
repository, path, record ID, JSON Pointer, immutable commit URL, original file
SHA-256, and actual download timestamp. Commentary has separate provenance from
the sūtra catalog. Original source strings and metadata survive unchanged;
normalized search representations are kept separately.
Credit Ashtadhyayi.com, Neelesh Bodas and contributors, and cite each returned source URL when using results. Commentary file labels identify the source work or upstream explanation collection; modern explanations must not be attributed to Pāṇini. See third-party notices and the upstream credits.
Our code is MIT licensed. Upstream data is not covered by our MIT license. The upstream README permits reuse with appropriate credit; no blanket SPDX data license is asserted here. The package does not bundle the corpus.
Evidence-first demonstration
uv run ashtadhyayi-mcp demo 'इको यणचि इत्यस्य अर्थः कः?'
uv run ashtadhyayi-mcp demo '6.1.87'This small replaceable client calls the server through MCP before displaying
source quotations and citations. It is an extractive demonstration, not a
general conversational LLM: it identifies a numbered sūtra or searches the query,
declines to choose between multiple matches, and does not invent an explanation.
An optional answerer interface and an evidence-first instruction are available in
demo.py for a future model integration. No API key is required and no question
is sent to an external model.
Development and tests
See the recorded test results for the latest local full-corpus audit, transport checks, package verification and timing measurements.
uv run pytest
uv run ruff check .
uv run mypy
uv build
# Validate a full synced corpus in addition to offline fixtures:
ASHTADHYAYI_INTEGRATION_DATA_DIR="$HOME/.cache/ashtadhyayi-mcp" uv run pytest -m integrationUnit, stdio, and demo evaluation tests are offline. The full-profile integration audit walks every form field and slot, verifies source reconstruction, covers all ten gaṇas represented in the files, and checks the known encoding gaps. Golden tests cover the derivation families, stored lakāras, both prayogas, person/number, case/number, gender ambiguity, pronouns, empty slots, alternatives and reverse lookup. These checks verify faithful retrieval, not scholarly correctness of every engine output. Integration tests are skipped unless an explicit data directory is supplied. Fixtures contain small attributed upstream excerpts; synthetic records used to test malformed data are clearly separate. See contributing, architecture, research, and ADR.
Available Tools
11 toolsget_dhatuBRead-onlyIdempotent
Exact dhātu lookup; returns all ambiguous matches with pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | text | |
| limit | No | ||
| query | Yes | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, so the safety bar is covered. The description adds genuinely useful context beyond them: exact lookups can still yield multiple ambiguous matches, and results are paginated. It omits any note on auth or result ordering.
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 tight sentence with the lookup semantics front-loaded and no filler. It is efficient, though the very compactness is part of why parameter detail is missing.
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?
An output schema exists, so return structure need not be described. But for a 4-parameter tool with zero schema coverage, the description leaves the `by` lookup mode and pagination bounds unaddressed, leaving a real gap before an agent can invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 4 parameters, so the description must carry the load. It implies the query is matched exactly and that limit/offset exist ('pagination'), but never explains the `by` enum (text / upstream_id / baseindex), which is the most consequential parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (lookup) and resource (dhātu) with the qualifier 'exact', which implicitly contrasts with the sibling search_dhatus. It does not name the sibling outright, so full differentiation requires the agent to infer from the name.
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?
'Exact dhātu lookup' implies you should use this when you have a precise query and search_dhatus when you don't, but no explicit when-to-use, when-not, or alternative is ever stated. Usage 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.
get_dhatu_formsCRead-onlyIdempotent
Retrieve stored finite and kṛdanta paradigms; paginate all sources. Missing forms do not imply invalidity. No generation or prefix composition.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | text | |
| pada | No | ||
| limit | No | ||
| query | Yes | ||
| family | No | ||
| lakara | No | ||
| offset | No | ||
| vacana | No | ||
| prayoga | No | ||
| purusha | No | ||
| category | No | ||
| pratyaya | No | ||
| derivation | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the burden. The description adds meaningful context beyond that: 'Missing forms do not imply invalidity' warns that empty results are meaningful, and 'No generation or prefix composition' clarifies retrieval-only behavior. The pagination note is also useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the core purpose followed by two important caveats. It avoids waste, though the phrase 'paginate all sources' is slightly cryptic and could be clearer.
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 tool with 13 parameters, 0% schema description coverage, and many enum-constrained fields, the description is incomplete for correct invocation. While an output schema exists and annotations cover safety, the missing usage guidance and parameter semantics leave significant gaps.
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 0% for 13 parameters, so the description must carry the full explanatory burden. It does not describe any parameter (e.g., query, by, pada, lakara, limit, offset) or how filters interact. The single mention of 'paginate' is far too vague to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('stored finite and kṛdanta paradigms'), making the tool's function clear. It distinguishes itself from generative tools by explicitly excluding 'generation or prefix composition,' though it does not name a specific sibling alternative.
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?
There is no explicit guidance on when to use this tool versus siblings like get_dhatu, search_dhatus, or get_form_coverage. The caveat 'Missing forms do not imply invalidity' is useful but does not tell the agent when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_form_coverageARead-onlyIdempotent
Report loaded form sources, omissions and unparsed groups; coverage is never exhaustive of Sanskrit.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and not-open-world, so the safety profile is covered. The description adds genuine value beyond that by warning that coverage is never exhaustive of Sanskrit, i.e. results must not be treated as a complete inventory — a meaningful interpretation caveat. It does not, however, explain what triggers omissions or unparsed groups.
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 with a semicolon-separated caveat; every clause carries information and there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, and with no parameters it need not document inputs. It covers the purpose and the key completeness caveat, leaving only the interpretation of 'omissions' vs 'unparsed groups' implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. No parameter information is missing.
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 ('Report') and a specific resource ('loaded form sources, omissions and unparsed groups'), so an agent can tell this is a data-coverage/diagnostics tool rather than a lookup. It does not name or contrast itself with the lookup siblings (lookup_form, get_dhatu_forms, get_shabda_forms), which is the only thing keeping it from 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?
No when-to-use guidance is given: nothing says whether to call this to validate results, before bulk queries, or to diagnose missing forms. The closing caveat hints the output is partial but does not tell the agent what to do with that fact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_shabdaBRead-onlyIdempotent
Retrieve śabda entries without dropping gender or lexical ambiguity.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | text | |
| limit | No | ||
| linga | No | ||
| query | Yes | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds one genuine behavioral fact beyond that: results preserve gender and lexical ambiguity rather than resolving senses. It says nothing about multiplicity of returned senses, ordering, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with zero filler, and the core action is front-loaded. It is efficient, though the extreme brevity leaves needed detail out rather than being genuinely complete.
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 5-parameter, zero-coverage schema tool, the description omits parameter meanings, matching semantics, and result cardinality. The presence of an output schema excuses it from describing return values, but the input contract is almost undocumented.
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 5 parameters at 0% schema description coverage, the description carries the full burden, yet it only indirectly alludes to one parameter ('gender' -> linga) without stating the P/S/N/A codes. The 'by' selector (text vs upstream_id), limit, and offset are entirely unexplained, as is whether query is exact or prefix-matched.
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 (Retrieve) and resource (śabda entries), which distinguishes it from the search_* siblings in the verb itself. However, it never names search_shabdas or explains that this is the exact/direct-fetch counterpart, so the differentiation is left implicit.
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 clause 'without dropping gender or lexical ambiguity' implies when to prefer this tool (when fidelity of linga/ambiguity matters), but there is no explicit when-to-use or when-not-use statement and no alternative is named. Usage must be inferred from a phrase about output quality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_shabda_formsBRead-onlyIdempotent
Retrieve stored śabda paradigms with 24 case/number slots, alternatives and empty slots preserved. Vibhakti 8 means vocative.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | text | |
| limit | No | ||
| linga | No | ||
| query | Yes | ||
| offset | No | ||
| vacana | No | ||
| vibhakti | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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 earns credit for disclosing result-shape behavior beyond the annotations: 24 case/number slots with alternatives and empty slots preserved, which tells the agent not to expect a normalized/compacted paradigm.
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 tight sentences with the core retrieval behavior front-loaded and the vibhakti convention appended. Nothing is wasted, though the vocab/convention aside could be folded more economically.
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?
An output schema exists so return structure is partly covered, but a 7-parameter query tool with zero schema descriptions leaves key semantics undocumented: filter meanings (linga/vacana/vibhakti), the query/by interaction, and pagination behavior. The description is too thin for this parameter surface.
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?
Seven parameters with 0% schema description coverage, yet the description only glosses one value (vibhakti 8 = vocative). Domain terms like linga, vacana, and the by=text vs by=upstream_id switch, as well as limit/offset paging, are never explained, so the description fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: retrieving stored śabda paradigms. It distinguishes itself from get_shabda by promising the full paradigm (24 slots) rather than a single entry, though it does not explicitly name sibling tools or contrast with get_dhatu_forms/search_shabdas.
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?
There is no when-to-use guidance, no mention of when to prefer get_shabda or search_shabdas, and no stated prerequisites. The agent must infer usage entirely from the name and the retrieval verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_sutraBRead-onlyIdempotent
Retrieve a sūtra and paginated source commentaries with provenance.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | ||
| commentaries | No | ||
| commentary_limit | No | ||
| commentary_offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds only that results are paginated and carry provenance; it omits pagination semantics, defaults, or commentary-selection effects.
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 with no filler, but it is so compressed that it under-specifies rather than being optimally concise.
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?
An output schema exists, so return values need not be restated. Still, for a four-parameter tool with zero schema documentation, the description leaves the required identifier and pagination behavior underspecified.
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 0% across four parameters, so the description must compensate and largely does not. 'Paginated' loosely hints at commentary_limit/commentary_offset and 'commentaries' hints at the array parameter, but the required 'number' identifier and the enum values (sutrartha, kashika) are never explained.
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 names a specific verb ('Retrieve') and resource ('a sūtra') and adds the scope of what comes back ('paginated source commentaries with provenance'). It does not, however, distinguish itself from the sibling get_sutra_context, leaving the agent to guess at the boundary.
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?
There is no statement of when to use this tool versus search_sutras or get_sutra_context, nor any prerequisite or exclusion. The agent gets a purpose but no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_sutra_contextCRead-onlyIdempotent
Retrieve numeric neighbors and raw context metadata; no inference.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| number | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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 one useful behavioral fact, that results are raw with no inference applied, but says nothing about behavior when the number is not found or how neighborhood bounds interact.
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 with no filler; the retrieval action comes first and the constraint ('no inference') follows. It is efficient, though the extreme brevity contributes to the gaps in other dimensions.
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?
An output schema exists, so return values need no explanation. However, with 3 parameters at 0% schema description coverage and no usage guidance, the description is too thin to let an agent invoke this confidently relative to its many siblings.
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 0%, so the description must carry parameter meaning, but it only loosely implies that 'numeric neighbors' corresponds to before/after. It never explains that 'number' is a string identifier (maxLength 32) nor that before/after are bounded neighbor counts of 0-5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb and resource: retrieve numeric neighbors plus raw context metadata. 'Numeric neighbors' distinguishes it reasonably from get_sutra (single item) and search_sutras (querying), though the phrase 'raw context metadata' is vague about what exactly is returned.
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?
There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The closing phrase 'no inference' hints at a contrast with some inferring operation, but that contrast is never made concrete for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_formBRead-onlyIdempotent
Reverse lookup of exact stored forms; returns all occurrences with pagination. Ambiguity is preserved. No sandhi analysis or grammatical validation.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | all | |
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| include_vocative_alias | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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 real value beyond that: pagination behavior, that all occurrences are returned, and that ambiguity is deliberately not resolved and no sandhi/grammatical processing occurs.
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 core action and followed by the key behavioral caveats. No filler, though the phrasing is terse enough that a little more specificity would not have hurt.
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?
An output schema exists, so return values need not be described. However, with five parameters at 0% schema coverage and no mention of filtering or the vocative alias flag, an agent lacks enough to invoke this correctly beyond the single required query.
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 0% across 5 parameters, and the description mentions none of them. Non-obvious parameters like kind (dhatu/shabda/all) and include_vocative_alias are left entirely unexplained, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Reverse lookup of exact stored forms' with the behavior 'returns all occurrences with pagination.' It is distinguishable from sibling search_* tools by emphasizing exact/reverse lookup, but it never names an alternative to sharpen the boundary.
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 negative guidance ('No sandhi analysis or grammatical validation') and notes ambiguity is preserved, which implies when this tool is appropriate, but it does not state when to prefer it over search_shabdas/search_dhatus or what input form is expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_dhatusCRead-onlyIdempotent
Literal lexical search of upstream dhātu and meaning fields.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description does add one real behavioral fact: matching is literal/substring rather than semantic, and it scopes the searched fields. It says nothing about result ordering, total-count behavior, or what happens with noisy/multiword queries.
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 with no padding; the matching mode and field scope come first. It is arguably under-specified rather than verbose, which is a completeness problem, not a structural one.
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?
An output schema exists so return values need not be explained, but for a search tool sitting among eleven siblings with zero schema parameter coverage and no usage routing, the single sentence leaves too much to inference. Pagination params and the alternative retrieval tools are never addressed.
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 0%, so the description must carry the load; it partially does by stating that 'query' is matched against dhātu and meaning fields, which is the key semantic the schema omits. However, limit and offset (ranges, defaults, pagination interaction) get no mention, and match semantics (case sensitivity, whole-word vs substring) remain unstated.
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?
It names a verb (search) and a resource (dhātu) and signals the matching mode with 'literal lexical', which implies a contrast with relevance/semantic search over shabdas. But 'upstream dhātu and meaning fields' is unexplained jargon and it never names a sibling (get_dhatu, search_shabdas) to disambiguate scope.
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?
No when-to-use condition, no prerequisites, and no mention of alternatives such as get_dhatu for a known entry or search_shabdas for word lookup. 'Literal lexical' only weakly implies the contrast; the agent must infer routing from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_shabdasCRead-onlyIdempotent
Lexical search of the upstream śabda catalog and meanings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| linga | No | ||
| query | Yes | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds that the search is lexical and targets an upstream catalog and meanings, but does not explain pagination behavior, result format beyond the output schema, or rate limits.
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 with no filler. It is appropriately concise, though arguably too terse given the four-parameter search interface and specialized 'linga' filter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values and annotations cover safety, but the description omits all parameter semantics and any usage guidance. For a four-parameter search tool with 0% schema description coverage, this leaves important gaps.
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 0% and the description mentions none of the four parameters. Critical semantics for 'linga' (enum values P/S/N/A), 'limit', and 'offset' are left entirely to inference from bare names and types.
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 (śabda catalog) with scope (lexical). Does not explicitly distinguish from sibling tools such as get_shabda or search_dhatus, but an agent can infer the difference from the resource name.
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?
No when-to-use guidance, no prerequisites, and no named alternatives. The agent must infer that this is for searching shabdas versus retrieving a single shabda or searching dhatus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_sutrasBRead-onlyIdempotent
Literal lexical search of sūtra text and upstream word metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral trait, that matching is literal/lexical rather than semantic, but says nothing about pagination behavior, ranking, or result size, which matter for a search tool with limit/offset.
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 with zero waste, putting the search scope and matching mode first. It is efficient, though the terseness trades away some needed detail.
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?
An output schema exists, so return values need not be described. However, for a paginated search tool with 0% parameter documentation, the description leaves gaps about paging and what part of the sūtra text is matched that an agent would need to call it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and none of the three parameters (query, limit, offset) are explained in the schema. The description specifies the search corpus ('sūtra text and upstream word metadata'), which clarifies the query parameter, but limit/offset paging semantics and query syntax remain undocumented.
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 (sūtra text and upstream word metadata), and the qualifier 'literal lexical' distinguishes it from semantic-style search siblings like search_dhatus and search_shabdas. It stops short of naming an alternative outright, so it is clear but not fully differentiated.
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?
No when-to-use or when-not-to-use guidance is given. With six sibling search/get tools available, the agent gets no explicit routing signal; the only hint is the implicit 'literal lexical' scope.
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.
11 tool updates
v0.2.0- First observed
get_dhatu - First observed
get_dhatu_forms - First observed
get_form_coverage - First observed
get_shabda - First observed
get_shabda_forms - First observed
get_sutra - First observed
get_sutra_context - First observed
lookup_form - First observed
search_dhatus - First observed
search_shabdas - First observed
search_sutras
TDQS
Scored across 11 tools
Each tool targets a distinct retrieval mode: exact entity, lexical search, context, stored forms, reverse lookup, or coverage. The descriptions carefully separate similar-sounding operations, leaving no meaningful overlap.
Names follow a clear snake_case verb_noun convention: get_* for exact retrieval, search_* for lexical search, and lookup_form for reverse lookup. The one deviation is semantically justified and does not disrupt predictability.
With 11 tools, the server is well-scoped for its retrieval domain. Each tool covers a distinct facet without redundant operations or excessive fragmentation.
The surface covers sutras, dhatus, shabdas, stored paradigms, reverse form lookup, and coverage reporting, with explicit limitations acknowledged. No obvious retrieval operation is missing for the stated read-only Sanskrit grammatical domain.
Maintenance
Related MCP Connectors
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Read-only semantic search over Vedic scripture verses, commentaries, and recorded lectures.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Read-only Remote MCP for externally grounded AI agent trust receipts.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA headless local knowledge library and RAG substrate that enables LLM clients to search, retrieve chunks, and list documentation packs through read-only MCP tools.MIT
- AlicenseNot gradedqualityBmaintenanceProvides LLM agents with a structured, queryable, local-first knowledge base with typed documents and full-text search via MCP.MIT
- FlicenseNot gradedqualityCmaintenanceRead-only MCP server for querying an evidence-aware knowledge vault with temporal and provenance-aware data, supporting agent memory and semantic graph projections.-
- AlicenseNot gradedqualityBmaintenanceA read-only MCP server that lets AI agents search and retrieve the Wheel of Heaven corpus, including source-grounded facts, interpretations, and comparative traditions, all with full epistemic metadata.20 npmCreative Commons Zero v1.0 Universal