Provides read-only evidence retrieval from a PostgreSQL database (rag_sag.yrb3_v3 schema), with tools for document overviews, evidence search, cross-paper comparison, entity expansion, spatiotemporal filtering, and source tracing.
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., "@YRB-HES Evidence MCP Find evidence comparing water quality trends across the Yellow River Basin"
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.
Acknowledgement
This project is deeply inspired by Zleap-AI/SAG. We sincerely thank the SAG contributors for the Event/Entity organization, graph-oriented retrieval, and evidence synthesis ideas that shaped this adapter.
YRB-HES Evidence MCP is an independent YRB3 adaptation. Please consult and respect the upstream SAG license and attribution requirements when reusing SAG materials.
YRB-HES Evidence MCP is a read-only Model Context Protocol (MCP) server for evidence retrieval in Yellow River Basin human–earth systems reviews. It exposes bounded access to the rag_sag.yrb3_v3 PostgreSQL schema and preserves source provenance for every returned claim.
The service connects document metadata, abstract screening, heading/subchunk context, SAG Event/Entity associations, verified edges, optional BGE-M3 vector recall, structured spatial/temporal evidence, and the geospatial tables copied into rag_sag.yrb3_v3. Geocoded canonical entities, hydro relations, source boundaries, spatial units, and audit rows retain their original table names; the former yrb3.public copy is an archive, not an active MCP source. Production pipelines remain responsible for Qwen extraction, database writes, and audit runs.
Related MCP server: DeepLaw
Tool | Purpose |
| Verify database identity, schema, tables, and current counts |
| Describe actual tables/columns and semantic data layers in the unified v3 foundation; defaults to a compact summary and accepts |
| Map a user concept or alias to registered YRB-HES semantic fields |
| Validate and structure a caller-defined five-layer contract for retrieval, evidence, analysis, response, and validation |
| Inspect one document's processing coverage |
| Retrieve lexical/vector/Event/Entity/spatiotemporal evidence |
| Build bounded cross-paper comparison rows |
| Read local heading and source context |
| Find canonical SAG entities |
| Expand entities to Events, evidence, edges, and geocode |
| Filter structured spatial/temporal evidence |
| Look up coordinates and verdicts for geocoded spatial entities (min_score filter, doc_refs provenance) |
| Return geocoded spatial entities linked to one document |
| Condensed verification brief for one entity: evidence quotes, abstract sentence, optional full-text hits |
| Trace IDs back to Markdown content and hashes |
search_evidence and compare_evidence accept compact=True to trim responses to identifiers, quotes and citations (~10x smaller for interactive use).
build_question_schema is question-agnostic and planning-only. It does not register, classify, or infer scientific question modules. The caller or Agent may supply any opaque question_id (for example D1Q1) together with the population, analysis unit, deduplication keys, measures, evidence policy, boundary policy, retrieval tools, and expected output claims. The builder validates and structures that contract without executing retrieval, modifying data, or exposing arbitrary SQL.
describe_data_foundation discovers the geospatial tables in the same rag_sag.yrb3_v3 schema as the literature and SAG tables. The response retains the geocode_sidecar key for client compatibility, but it is a compatibility projection rather than a second database connection. The default summary lists table and column names without expanding every database-column descriptor; request detail=full when full column metadata is needed. Geocode fields such as coordinates, score, verdict, in_yrb9, and in_yrb_hydro describe spatial normalization only and do not replace formal study-area evidence or perform scientific-question analysis.
The server is read-only: it performs no DDL, DML, UPSERT, deletion, model inference, or extraction. Use exact document_id, subchunk_id, Event/Entity IDs, evidence IDs, heading paths, and source hashes in downstream synthesis.
git clone <repository-url> yrb_hes_mcp
cd yrb_hes_mcp
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .The runtime requires Python 3.11+ and PostgreSQL access. The default connection targets dbname=rag_sag through the remote Unix socket. Set YRB3_MCP_DATABASE_URL only when a controlled alternative is required; the legacy YRB3_MCP_GEOCODE_DATABASE_URL is no longer used.
cd /home/wst/projects/yrb_hes_mcp
PYTHONPATH=/home/wst/projects/yrb_hes_mcp \
/home/wst/projects/yrb_hes_mcp/.venv/bin/python \
-m mcp_server.serverRegister the same SSH-stdio command in the Codex MCP configuration. Keep database credentials outside the repository.
python -m pytest tests/test_import.py
python tests/protocol_smoke.py
python tests/current_state_audit.pyA passing protocol smoke verifies transport and tool contracts. It does not certify full-corpus processing or scientific validity.
Call healthcheck before retrieval. Use search_evidence for discovery, compare_evidence for cross-paper scaffolding, and trace_source before quoting. Keep publication year distinct from study-evidence year. Treat spatial labels as candidates until the formal research-area field or source wording confirms them. If the edge table is empty, report the available Event–Entity neighborhood without inventing edges. Always report coverage, warnings, and conflicts.
Coverage depends on the current Qwen, Embedding, spatiotemporal, and Edge processing state in rag_sag.yrb3_v3. The MCP provides retrieval and provenance; the Agent and human reviewer remain responsible for scientific interpretation and final acceptance.
We sincerely thank Zleap-AI/SAG and its contributors. SAG's structured Event/Entity, graph, and retrieval-enhancement design provided important methodological foundations for this cross-paper evidence index. This project adds YRB3-specific database contracts, human–earth systems categories, spatiotemporal evidence, and Markdown source tracing.
MIT. See LICENSE.
Build bounded cross-paper comparison rows with claims, entities, spatiotemporal evidence and source locators.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum Subchunk hits used to build comparison rows | |
| query | Yes | Research question or comparison topic | |
| year_to | No | Optional publication year upper bound | |
| language | No | zh, en, or empty | |
| year_from | No | Optional publication year lower bound | |
| request_id | No | Optional audit request ID | |
| document_ids | No | Optional exact document IDs | |
| evidence_year_to | No | Optional study-evidence year upper bound | |
| evidence_year_from | No | Optional study-evidence year lower bound |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. 'Build bounded cross-paper comparison rows' hints at a limit but doesn't explain how the tool operates (e.g., it queries subchunks, how rows are aggregated, what 'bounded' means exactly, or any side effects). The description lacks detail on the process or output structure beyond high-level content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the core purpose and key output elements without redundancy. Every word adds value.
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?
While the schema provides parameter details and the output schema exists, the description lacks an overview of how the tool fits into a workflow. It doesn't explain what 'comparison rows' are, how they differ from sibling tool outputs, or when to invoke it. For a tool with 9 parameters and multiple siblings, this is a notable gap in usability guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no parameter-specific meaning, which matches the baseline of 3. It does not clarify how parameters like 'limit' or 'document_ids' influence the comparison rows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Build') and resource ('bounded cross-paper comparison rows'), and specifies the content (claims, entities, spatiotemporal evidence, source locators). This distinguishes it from siblings like search_evidence or get_spatiotemporal_evidence, which focus on retrieving individual pieces rather than building comparison rows.
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 use case is implied by the phrase 'cross-paper comparison' but no explicit when-to-use or alternative suggestions are provided. The description doesn't mention when to prefer this over search_evidence or trace_source, leaving usage to be inferred from the tool name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expand one canonical entity to linked Event, Subchunk, spatiotemporal evidence and verified edges.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| entity_id | Yes | Exact v3_sag_entities.entity_id | |
| request_id | No | Optional audit request ID |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not disclose whether the operation is read-only, what side effects may occur, whether pagination is applied, or what happens if the entity_id is invalid. The mention of 'expand' and linked data hints at a graph traversal but lacks behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the main action and outcome, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and an output schema, the description is minimal. It does not explain what 'verified edges' means, whether there are performance implications, or how the linked items are presented. The output schema may cover return structure, but the description lacks sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention parameters at all. The schema already documents entity_id with 'Exact v3_sag_entities.entity_id' and limit constraints, but the description adds no meaning beyond what the schema provides. With schema coverage at 67%, the description could have helped clarify parameter usage but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('expand') and the resource ('canonical entity'), and specifies the output types (Event, Subchunk, spatiotemporal evidence, verified edges). This distinguishes it from siblings like search_entity and get_subchunk_context, though it does not explicitly name an alternative tool.
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 explicit guidance on when to use this tool versus alternatives. The description implies usage for a given entity_id but does not mention exclusions or recommend other tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return metadata, abstract screening, heading, Subchunk, SAG and spatiotemporal counts for one document.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | No | Optional audit request ID | |
| document_id | Yes | Exact v3 document_id |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explicitly state that the operation is read-only, nor does it mention required permissions, potential errors, or rate limits. The word 'Return' implies a read but is not explicit about non-destructiveness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and resource, and it efficiently lists the output categories without any fluff. Every word is necessary and informative.
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 presence of an output schema covers return-value details, and the description lists the main content areas well. However, it lacks any usage context or guidance on when this overview tool is appropriate, which prevents a perfect score. Given the moderate complexity and available schema, it is still sufficiently complete for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents document_id as 'Exact v3 document_id' and request_id as an optional audit request ID. The description adds minimal extra parameter meaning—it only reinforces that the tool operates on a single document. With 100% schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Return' as a specific verb and identifies the resource ('one document'), then enumerates the exact content (metadata, abstract screening, heading, Subchunk, SAG, spatiotemporal counts). It clearly distinguishes this from sibling tools like get_subchunk_context, which focuses on a single subchunk rather than a document-level overview.
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 guidance is given about when to use this tool versus alternatives like search_evidence or get_subchunk_context. The description simply states what it does, without any contextual advice, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query structured spatial and temporal evidence with document, Subchunk and research-area filters.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| request_id | No | Optional audit request ID | |
| document_id | No | Optional exact document_id | |
| subchunk_id | No | Optional exact subchunk_id | |
| evidence_type | No | spatial or temporal | |
| is_research_area | No | Optional formal study-area gate | |
| normalized_label | No | Optional label fragment |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for disclosing behavioral traits. While 'Query' implies a read-only operation, the description does not explicitly state read-only behavior, pagination, return format, or any side effects. It only restates the purpose without adding behavioral context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently conveys the core purpose and filter types, earning its place without unnecessary 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?
The tool has 7 parameters and no annotations, yet the description is minimal. It omits context about the evidence_type parameter, limit behavior, and how it relates to sibling tools. Although an output schema exists, the description is too thin to fully guide an agent for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), so the baseline is 3. The description adds value by grouping key parameters into 'document, Subchunk and research-area filters', but it omits other parameters like evidence_type and limit, which are covered by the schema. Overall, the description provides a helpful summary but does not fully compensate for the one undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Query'), a specific resource ('structured spatial and temporal evidence'), and lists the key filter dimensions (document, Subchunk, research-area). This distinguishes it from sibling tools like search_evidence or compare_evidence by emphasizing the spatiotemporal scope and specific filter types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by naming the filters, but it does not explicitly state when to choose this tool over alternatives, nor does it provide exclusions or contrast with sibling tools. It is clear about the input filters but lacks any guidance on use cases or alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one Subchunk, its title path, adjacent context and linked Event/spatiotemporal evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| radius | No | Reserved context radius | |
| request_id | No | Optional audit request ID | |
| subchunk_id | Yes | Exact v3_text_chunks.subchunk_id |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden but only lists output components. It does not disclose whether the operation is read-only, how 'adjacent context' is measured, any performance implications, or edge cases such as missing subchunk 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?
The description is a single, front-loaded sentence with a clear verb and no filler. Every word contributes to conveying the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read operation with an output schema and fully described parameters, so the description is somewhat adequate. However, it lacks usage context, radius semantics, and any behavioral caveats, making it minimally complete rather than fully contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a slight semantic hint by linking 'adjacent context' to the tool's output, but it does not clarify the radius parameter's behavior beyond the schema's vague 'Reserved context radius'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a single Subchunk with title path, adjacent context, and linked Event/spatiotemporal evidence, using a specific verb and resource. It does not explicitly differentiate from sibling tools like get_spatiotemporal_evidence, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The usage is only implied by the tool's name and description, with no explicit decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check PostgreSQL, yrb3_v3 tables, read-only identity and current row counts.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | No | Optional audit request ID |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden for behavioral disclosure. It does not state whether the tool is read-only, what permissions are needed, or whether it has side effects. The phrase 'read-only identity' suggests a check for read-only status but does not explicitly confirm the tool itself is non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action ('Check') and enumerates the specific items checked. It contains no extraneous words and is efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists what is checked but omits context such as the purpose of the healthcheck, what 'read-only identity' entails, and when an agent should invoke it. An output schema exists, so return values are covered, but the description remains somewhat minimal for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter, request_id, is fully described in the schema as an optional audit request ID. The description adds no extra meaning about this parameter, but with 100% schema description coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with the specific verb 'Check' and names precise resources: 'PostgreSQL, yrb3_v3 tables, read-only identity and current row counts.' This clearly distinguishes it from the sibling evidence/search tools by indicating a health-monitoring purpose rather than data retrieval.
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 guidance is provided on when to use this tool versus alternatives or exclusions. The description only states what it checks, leaving usage entirely implied. There is no mention of conditions like 'run before other queries' or 'use for diagnostics.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search canonical SAG entities by name, alias key and optional entity type.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Entity name or canonical key | |
| limit | No | ||
| request_id | No | Optional audit request ID | |
| entity_type | No | Optional entity type |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the search action and criteria, but does not explicitly state that it is read-only, does not mention auth requirements, rate limits, or any side effects. For a search tool this is a notable omission, though 'search' implies a low-risk operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that identifies the verb, resource, and key criteria. Every word contributes value, and there is no unnecessary repetition or 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?
Given the existence of an output schema, return values are covered, and the description states the core purpose and main parameters. However, it lacks usage guidance and behavioral caveats, and does not mention any limitations on search scope or result handling, making it only minimally complete for a tool with no annotations and multiple 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 75%, and the tool description adds a small amount of meaning by introducing 'alias key' as a searchable variant of name and confirming entity_type is optional. However, the 'limit' parameter has no schema description and the tool description does not compensate for that gap, leaving its semantics to be inferred from the title.
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 the specific verb 'Search' with a specific resource ('canonical SAG entities') and search criteria ('by name, alias key and optional entity type'). It clearly distinguishes this from sibling tools like search_evidence, which search evidence, and expand_entity, which expands related entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use when looking up entities by name or alias. However, it does not explicitly compare to alternatives or state when not to use this tool. There is no mention of search_evidence or other sibling tools, so guidance on alternatives is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search YRB3 evidence with exact if_yrbhg gate, lexical Subchunk recall, Event expansion and spatiotemporal attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum Subchunk hits | |
| query | Yes | Research question or terms | |
| year_to | No | Optional publication year upper bound | |
| language | No | zh, en, or empty | |
| year_from | No | Optional publication year lower bound | |
| request_id | No | Optional audit request ID | |
| document_ids | No | Optional exact document IDs | |
| evidence_year_to | No | Optional study-evidence year upper bound; overlaps temporal value_start/value_end | |
| evidence_year_from | No | Optional study-evidence year lower bound; overlaps temporal value_start/value_end |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It mentions internal mechanisms like 'exact if_yrbhg gate' and 'lexical Subchunk recall', which suggest filtering and retrieval behavior, but it does not explicitly state safety (read-only), limitations, or side effects. Some behavioral context is added but not enough for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary action ('Search YRB3 evidence') followed by qualifying features. No redundant or filler words are present, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and fully-described parameters, the description fails to explain how this tool fits into the broader context of sibling tools or when to choose it over alternatives. The cryptic terms (YRB3, if_yrbhg) are not defined, leaving gaps in the agent's ability to assess completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any extra meaning to parameters beyond what the schema already provides. For a search tool, the schema descriptions are clear (e.g., 'Maximum Subchunk hits', 'Research question or terms').
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 'Search' and resource 'YRB3 evidence', making the core purpose clear. It also hints at distinct mechanisms (exact if_yrbhg gate, lexical Subchunk recall, event expansion, spatiotemporal attachment) that differentiate it from general search, though the jargon is not explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings (e.g., search_entity, get_spatiotemporal_evidence). There are no explicit recommendations, exclusions, or alternative references, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace an Event, Subchunk or spatiotemporal evidence ID back to Markdown content and hashes.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes | Exact event_id, subchunk_id or evidence_id | |
| request_id | No | Optional audit request ID |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It does not explicitly state that the operation is read-only or mention any side effects, authentication requirements, or error behavior. The description only states the input-output relationship.
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, concise sentence that front-loads the core functionality without any extraneous detail. Every word contributes to the purpose.
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 to define return values, the description sufficiently covers the tool's purpose for a straightforward lookup operation. However, it lacks any usage context or comparison to sibling tools, which slightly reduces its completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters, including the accepted ID types and the optional request_id. The description does not add any additional parameter semantics beyond what the schema already documents, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('trace') and resource (IDs to Markdown content and hashes), distinguishing it from sibling tools like search_evidence which search rather than trace.
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 guidance is provided about when to use this tool versus alternatives such as search_evidence or get_subchunk_context. The description only states the action, leaving the agent to infer appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0compare_evidenceexpand_entityget_document_overviewget_spatiotemporal_evidenceget_subchunk_contexthealthchecksearch_entitysearch_evidencetrace_sourceScored across 9 tools
Each tool targets a distinct operation: document overview, subchunk context, evidence search, comparison, entity search, entity expansion, spatiotemporal query, source tracing, and health check. Though search_evidence and get_spatiotemporal_evidence both deal with evidence, the former is full-text with event expansion while the latter is structured query with filters, so they remain clearly distinguishable.
Most tools follow a clear verb_noun pattern (get_document_overview, search_evidence, compare_evidence, expand_entity, trace_source). The lone exception is 'healthcheck', which is a single compound noun rather than a verb-led name, making it a minor deviation from the otherwise consistent convention.
With 9 tools, the server is well-scoped for its purpose. Each tool addresses a distinct aspect of evidence retrieval and exploration, from document-level overview to fine-grained spatiotemporal queries and source tracing, without unnecessary redundancy or bloat.
The read-only evidence surface is fairly comprehensive: it covers document overview, subchunk context, evidence search, comparison, entity retrieval/expansion, spatiotemporal filtering, and source tracing. A minor gap is the lack of a direct document listing method, though search_evidence can partially compensate by returning relevant documents.
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
